Skip to content

PATTERN Cited by 1 source

OpenAPI schema as agent tool contract

Pattern

Declare the set of tools an agent can invoke as a collection of OpenAPI schemas, and let a runtime gateway handle auth, request / response validation, retries, and rate limiting against the declared contract — instead of writing bespoke per-tool glue code inside the agent.

Canonical AWS disclosure, 2026-04-23: "These connections use tools defined with OpenAPI schemas as targets and Lambda-based integrations using AgentCore Gateway. AgentCore Gateway uses these OpenAPI specifications to understand API contracts, handle authentication, validate requests and responses, and manage retries." (Source: sources/2026-04-23-aws-modernizing-kyc-with-aws-serverless-solutions-and-agentic-ai.)

What "tool contract" means here

An agent tool is a named capability (verify_identity, query_sanctions_list, activate_account) with typed inputs and outputs. The OpenAPI schema for the capability carries:

  • Path + method: POST /kyc/verify-identity.
  • Request schema: typed JSON body; required fields; enums for risk level / jurisdiction.
  • Response schema: typed output; success + error shapes.
  • Auth requirements: OAuth2, mTLS, API key — declared, not hard-coded.
  • Extensions for the agent: tool description, usage examples, invocation constraints ("call only after identity-verification succeeded").

An AgentCore Gateway-class runtime reads the schema and becomes the tool executor: agent emits a typed tool call → gateway validates input → gateway authenticates → gateway invokes the underlying Lambda / HTTP endpoint → gateway validates response → gateway returns (or retries, or escalates) to the agent.

Why OpenAPI specifically (not custom JSON schema,

not MCP tool descriptors, not raw HTTP)

  • OpenAPI is the ambient enterprise-API contract format. Banks, insurers, and financial-services firms already publish their internal APIs as OpenAPI. No translation step to become an agent tool.
  • Tooling ecosystem is mature. Generators, validators, mock servers, contract-testing frameworks all exist.
  • Auth is first-class (OAuth2 flows, security schemes).
  • The runtime can type-check — agents emitting malformed tool calls fail fast at the gateway, not at the downstream API.

Contrast with MCP: MCP defines a wire protocol for agent–tool exchange that also requires tool schemas. They're complementary, not exclusive — MCP could in principle use OpenAPI-defined tools. The KYC post specifically uses OpenAPI schemas, via AgentCore Gateway, because the tool targets are existing internal banking APIs.

What moves out of the agent

Before this pattern: 

agent code:
  try:
    token = refresh_oauth2_token(client_id, ...)
    body  = {...}
    resp  = requests.post(url, json=body, headers={Authorization: token})
    if resp.status == 429: sleep(backoff); retry
    if not resp.json().matches(schema): raise InvalidResponse()
    return resp.json()
  except TimeoutException:
    retry with exponential backoff
    ...

After this pattern: 

agent code:
  result = tools.verify_identity(customer_profile)
  return result

All of: auth, retries, validation, rate-limit handling moves into the gateway. The agent's job is to pick the tool and interpret the result; everything else is the runtime's problem.

When to reach for it

  • Multiple external / on-prem APIs behind the agent, each with different auth, each changing independently.
  • Regulated environment where per-tool auth scopes have to be enforced at the runtime level, not the agent level.
  • Iterative rollout — new tools get added by shipping a new OpenAPI spec, not by changing agent code.
  • Existing OpenAPI specs already exist for the target APIs (most large enterprises).

Anti-patterns

  • Baking secrets into the prompt. The whole point of the pattern is to keep credentials out of prompt / agent state. Leak the secret to the model → leak the secret.
  • Letting the agent catch auth errors. If auth refresh is the gateway's job, the agent shouldn't see 401s — the gateway should transparently retry. If the agent sees them, the runtime is misconfigured.
  • Under-specifying the output schema. A permissive response schema means the gateway can't validate — malformed responses reach the agent, which hallucinates around them.

Relation to Identity and Supervisor

  • systems/agentcore-identity gates which agent can invoke which tool (authorisation); this pattern gates how the invocation happens (contract).
  • patterns/supervisor-subagent-kyc-orchestration: in that pattern, each specialised sub-agent carries a narrow OpenAPI-declared toolset. Identity + Gateway together are what enforce the tool-surface narrowing — without them it's just prompt discipline.

Seen in

Last updated · 476 distilled / 1,218 read