what gateway is for
agents need to do things — read a database, call a billing api, fire off a webhook. the gateway primitive is how those things become tools the agent can see, describe, and invoke. in production, agentcore gateway takes an openapi spec, a lambda arn, or a smithy model and exposes each operation as an mcp tool. the agent framework does the rest: llm sees the tool, llm decides to call it, gateway dispatches the call.
the part that gateway owns is the glue: auth, schema, rate limits, observability. the part you own is deciding which services your agent should reach, and with which scopes.
what a tool looks like
- name a stable identifier the agent uses to invoke the tool. usually derived from the function name or the openapi operationId.
- description one line of prose. this is what the llm reads when choosing whether to call the tool. vague descriptions = wrong tool calls.
- parameters a typed schema. in typescript you describe it with zod (or an equivalent json-schema-producing library) and gateway hands the compiled schema to the llm.
- handler the actual implementation — an async function, a lambda arn, a remote api. gateway doesn't care; it just needs something to dispatch to.
the smallest gateway
tools.register({...}) wires up the handler with a
name, description, and parameter shape, then traces the registration.
tools.call(name, args) is the same call an agent framework
would make on your behalf when the llm picks this tool.
tools inside an entrypoint
the real flow is: the agent's entrypoint runs, the llm decides to call a tool, gateway dispatches it, the tool returns, the agent continues. here we skip the llm and make the decisions ourselves — the shape of the code is the same.
notice the trace: every gateway.call gets its own event,
with the tool name and arguments, followed by a
gateway.result with the return value. in production these
become opentelemetry spans nested under the agent invocation — click
into an invoke in cloudwatch and you can see every tool call, its
latency, and its result.
schemas, errors, and unknown tools
two things gateway handles for you: describing tools to the agent and surfacing failures cleanly.
listTools() returns the metadata the llm would see — name,
signature, description. when a handler throws, gateway emits a
gateway.error span and propagates the exception so the
agent can handle it (or let it bubble). calling an unregistered tool
name fails fast with a gateway.miss event — a different
failure mode you want to distinguish in production.
how tools usually get registered in production
registering handlers in-process (like we did above) is the easiest way to demonstrate gateway, but it's rarely how teams actually do it. if your api already has an openapi spec — the standard yaml/json description used by swagger, stripe, github, and most modern services — you can point gateway at it directly, and every operation in the spec becomes an mcp tool automatically. no wrapper functions to write, no parameter schemas to copy, no validation code. the spec you already have is the tool registry.
the same is true for aws lambdas (gateway reads the handler's typed input) and smithy models (the internal aws api description language). whatever format you already describe your service with, gateway treats as the source of truth and generates the tool surface from it. you maintain the api; gateway keeps the agent's view of it in sync.
next: identity — who is the agent, and what is it allowed to touch.