Skip to main content

Contracts

The Contracts screen lets you read the JSON Schema of every v1 contract published by the Control Plane and validate a JSON or YAML document against it before you apply it. Portal path: /developer/contracts. It is used by developers and pack authors who write manifests (agents, skills, connectors, plugins, policies).

What the screen shows​

  • On the left, the list of the contracts from GET /v1/contracts, paginated: the title of the contract and its technical name.
  • JSON Schema: the schema of the selected contract (GET /v1/contracts/{name}), shown as JSON. The first contract of the list is selected by default.
  • Validate a document: a text area (JSON or YAML, {} by default) and the Validate button.
  • The result: Valid document with a green mark, or Invalid document with the list of the errors (path and message of each error).
  • A parse error message under the button when the text is neither JSON nor YAML.

Actions​

Button or actionWhat it doesAPI callRoles
Click a contract in the listShows its schema and clears the last result.GET /v1/contracts/{name}Every signed in user
ValidateParses the text, then sends it to the server for validation.POST /v1/contracts/{name}/validateEvery signed in user
Pagination of the listShows the next or previous contracts.NoneEvery signed in user
Retry (error state)Reads the contract list again.GET /v1/contractsEvery signed in user

Roles​

The three contract routes only need a signed in principal (current_principal in services/control-plane/src/eai/domains/contracts/__init__.py). The portal asks no role on this screen. Validating a document never stores it: applying a manifest is done elsewhere and needs tenant_admin or developer.

Typical tasks​

Check a skill manifest before applying it​

  1. Select the contract. Each kind of manifest has its own schema. Click skill-manifest in the list. Expected result: the JSON Schema section shows the schema. If it fails: an error state appears; click Retry.
  2. Paste the manifest. The server validates exactly what you paste. Paste the JSON or YAML text in Validate a document. Expected result: the text is kept as typed. If it fails: nothing to do at this step.
  3. Validate. Click Validate. Expected result: Valid document. If it fails: read each error line (path then message), fix the manifest and validate again; a parse error means the text is not valid JSON or YAML.

Find which fields a contract requires​

  1. Open the schema. Click the contract in the list. Expected result: its schema is shown. If it fails: an empty list shows No contract published; the Control Plane has no contract loaded.
  2. Validate an empty document. Leave {} and click Validate. Expected result: Invalid document with one error per missing required field. If it fails: check the network message of the error state.

Troubleshooting​

SymptomCauseFix
No contract publishedThe Control Plane found no contract.Check the deployment of the Control Plane and its contracts folder.
Error unknown_contract (404)The contract name does not exist.Choose a contract from the list.
Parse error under ValidateThe text is neither JSON nor YAML.Fix the syntax (quotes, commas, indentation).
Invalid document with errorsThe document breaks the schema.Fix each field named by the error path.
"The Control Plane API cannot be reached"The API is down or the API address of the portal is wrong.Check the Control Plane and the NEXT_PUBLIC_EAI_API_URL setting of the portal.