Defining Agent Interfaces: API Contracts and Schema Examples

Agent teams need precise, minimal API contracts so modules can be implemented, mocked, validated, and handed off with no guesswork. Below are practical patterns, file-layout suggestions, and concrete schema examples you can copy into a spec repository.

What to include in an agent-facing API contract

Keep contracts small, explicit, and machine-readable. At minimum include:

– A one-line purpose (what this endpoint/event does).
– Concrete endpoint or event name and location (HTTP path or topic).
– Input schema (JSON Schema / OpenAPI component / protobuf message).
– Output schema (success and error shapes).
– Example requests/responses (minimal runnable examples).
– Auth & rate limits (token required, scopes).
– Semantics (idempotency, ordering, retry hints).
– Version and changelog link.

Repository layout (simple, predictable)

/specs/
/specs/openapi.yaml — API surface for HTTP endpoints
/specs/schemas/*.json — reusable JSON Schema definitions
/specs/protos/*.proto — gRPC messages if used
/examples/
/examples/requests/*.json — example inputs
/examples/responses/*.json — example outputs
/tests/contract-validation.yml — CI job to validate specs

Example 1 — OpenAPI + JSON Schema (HTTP request/response)

Purpose: accept a content-summary job and return a job id.

OpenAPI component (YAML snippet):

paths:
/jobs:
post:
summary: Create summary job
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobRequest'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobResponse'
components:
schemas:
CreateJobRequest:
type: object
required: ["source_url","model"]
properties:
source_url:
type: string
format: uri
model:
type: string
CreateJobResponse:
type: object
required: ["job_id","status"]
properties:
job_id:
type: string
status:
type: string
enum: [queued, running, completed, failed]

Example request/response (examples/requests/create-job.json)

{“source_url”:”https://example.com/doc.pdf”,”model”:”summarizer-v1″}

Response (201): {“job_id”:”job_12345″,”status”:”queued”}

Example 2 — JSON Schema for event payloads (webhook or message)

Purpose: agents publish document.processed events with normalized metadata.

schemas/document.processed.json:

{
"$id": "https://example.com/schemas/document.processed.json",
"type": "object",
"required": ["document_id","processed_at","summary"],
"properties": {
"document_id": {"type":"string"},
"processed_at": {"type":"string","format":"date-time"},
"summary": {"type":"string"},
"tokens": {"type":"integer"},
"metadata": {"type":"object","additionalProperties": true}
}
}

Example 3 — protobuf for low-latency agent-to-agent RPC

protos/ingest.proto:

syntax = "proto3";
package agent;

message IngestRequest {
string document_id = 1;
bytes payload = 2;
}

message IngestResponse {
string status = 1; // OK, ERROR
string error_message = 2;
}

service IngestService {
rpc Ingest(IngestRequest) returns (IngestResponse);
}

Validation and CI

– Validate OpenAPI with tools like openapi-generator or swagger-cli.
– Validate JSON Schema with a linter (ajv / jsonschema).
– Run contract tests in CI: spin up a mock server from the spec, run example requests, and assert responses.
– Include contract diff checks to detect breaking changes and require reviewers to choose major/minor version bumps.

Testing pattern: provider & consumer contracts

– Provider test suite: ensures implementation matches spec. Run against the running service.
– Consumer contract tests: mock the provider using the spec and run consumer logic against the mock (use wiremock, prism, or generated stubs).

Practical tips

– Always publish a machine-readable spec at a stable path (e.g., /openapi.json).
– Keep examples minimal and runnable (one-liners where possible).
– Document error schemas and retry semantics; ambiguous errors cause most integration bugs.
– Prefer contract-first for cross-team integrations; use code-first for throwaway internal scripts.
– Use semantic versioning and include a changelog link inside the spec file.

Applying these patterns lets each agent implement, mock, and validate its module independently while guaranteeing interoperability through automated checks.

Sources

• API Contract Guide: Examples and Best Practices (Signeasy; 2026-02-09)
• API design best practices guide (March 2026) (Fern; 2026-03-31)