Define one tool contract before choosing an agent framework

A professional agent design begins with a business operation that can be described in plain language and checked by ordinary code. Use a fictional asset-registration service where the only permitted action is to read the registered status of a record in the current tenant. The request needs a validated asset ID and authenticated tenant context; its response needs source time, status and an explicit found/not-found indicator. Do not permit the model to choose the tenant identity by copying a number from retrieved prose. Define who owns the data, what should happen when no record exists and which side effects are prohibited.

This narrow starting point is more useful than connecting many tools. A model can produce a plausible function call without having observed the actual service state. The trusted executor must first compare the proposed name and arguments to a registry, authorize the target and then execute the permitted operation. Record the model’s proposal, the authorization result and the service’s response as distinct events. For related baseline patterns, see the existing Bedrock agent tools guide.

Separate AgentCore Runtime, Gateway and agent reasoning

An agent framework chooses how to plan or coordinate model calls; a runtime hosts executable agent code; and a gateway can expose governed tool endpoints. Treat these as different responsibilities, not synonyms. AWS’s AgentCore Gateway documentation explains how agents can discover and invoke configured targets through MCP. A gateway does not eliminate the need for authorization in the target service. Likewise, an agent’s system prompt is not an IAM permission grant.

Draw a four-part diagram: requesting user, agent/orchestrator, authenticated tool gateway and backend record system. On each connection, name the identity, protocol, resource boundary and observability evidence. Keep deployment credentials separate from the user prompt and from retrieved documents. If the gateway is unreachable, the model should not invent a successful lookup. If the backend returns a denial, the gateway should preserve it and the user-visible answer should say the result could not be confirmed. The diagram provides a concrete way to debug integration problems instead of blaming the language model for every failure.

Treat MCP capability negotiation as a versioned contract

Model Context Protocol gives an agent client a structured way to discover tools and invoke them. The supported protocol version matters because the initialization and session behavior differ. Current AWS documentation describes AgentCore Gateway support for multiple versions, including a 2026-07-28 stateless revision in which requests carry protocol-version metadata instead of relying on an earlier initialize handshake. Do not paste one version’s client initialization sequence into another without checking what the chosen gateway and SDK actually support.

Make a compatibility matrix with MCP version, transport, discovery operation, authentication mode and state expectations. Your test client should reject unsupported capabilities instead of silently pretending a tool exists. Treat each tool schema as a contract: required arguments, type constraints, allowed identifier format and exact error shape. A schema can help the model construct arguments, but the executor must validate those arguments again because model-generated JSON is untrusted. Include a deliberately malformed record ID and confirm the backend was never invoked for it.

Choose where an MCP server runs and how it is isolated

AWS also documents running MCP servers in AgentCore Runtime. An MCP server running inside a managed runtime and a target registered behind a gateway can serve different integration needs. Document the supported HTTP endpoint behavior, session handling and constraints of the selected deployment rather than assuming an MCP tutorial guarantees all stateful capabilities. Be explicit about which component performs transport authentication and which component checks authorization for each requested business record.

For a harmless lab, expose one synthetic lookup and a health test using an isolated development account and no customer data. Add a negative test with an invalid caller token and one with a valid caller attempting an out-of-tenant record. Both should fail before sensitive content is returned. If the runtime contains shared state, test two parallel synthetic users and verify that one session cannot observe the other’s context. Container or gateway success is only a connectivity test; it does not prove tenant isolation.

Make identity, scopes and approvals independent of prompts

The agent can decide that information is needed, but an authenticated caller determines what the tool is authorized to read. Prefer narrowly scoped IAM and service-side resource policies over a broad development role. Distinguish the agent’s infrastructure identity from a delegated end user’s authority when the service supports both. A trusted tool can use verified user context to filter records; a field named user_id in model-proposed arguments is not sufficient evidence of authorization.

Some workflows genuinely need side effects. If a ticket-update operation is later introduced, require a human or deterministic policy approval with the exact target, intended change and relevant prior state. After a network timeout, query the authoritative record before retrying. Without an idempotency strategy, an agent may submit an action twice and still tell the user it executed once. The existing agent-boundary analysis shows why limiting authority is an architectural feature, not a concession about model capability.

Test direct and indirect prompt injection at the tool boundary

Construct a legitimate request for the state of an allowed fictional asset. Then add two adversarial cases: the user requests a different tenant’s record, and a retrieved support note contains text instructing the agent to call a privileged tool. Retrieved notes and tool outputs are lower-trust data. The target service must apply its own authorization rules even if the model misreads the instruction boundary. A successful security design can contain an unsafe proposal without leaking the record.

Use a two-column evaluation: model intent and application outcome. Mark the proposed tool name, proposed arguments, execution permission, actual execution and final response separately. If a model asks for a forbidden tool but the executor denies it, record a model-level security failure and a containment success; do not give the entire system a clean grade based solely on its polite final answer. Include a benign question that discusses injection syntax without requesting execution so the evaluation also rewards useful analysis of suspicious text.

Manage state and stopping rules without hidden loops

Agent memory and runtime session state need deliberate lifetimes. A conversation identifier is not a grant to retrieve records from a prior user’s session. Document what the agent is allowed to remember, where it is stored and how deletion or access revocation propagates. Use a limited number of steps, a request deadline and a maximum tool count to prevent costly reasoning loops. Keep a small trace record with correlation IDs and operation outcomes; redact user content when logging it would expose confidential material.

Test three failure conditions: a tool returns not found, a tool times out before execution and a tool responds after a client-side deadline. The safe user response differs in each case. A timeout is an unknown outcome unless a trusted layer can establish whether the operation completed. For side-effecting tools, never translate an uncertain status into a success message. The multi-agent workflows guide helps show why additional agents tend to multiply state and coordination obligations.

Measure the tool pathway instead of only answer fluency

Evaluate the complete action pathway on a fixed set of synthetic cases. Record whether the tool choice was appropriate, whether the arguments referred to the authorized record, whether the gateway returned a permitted result, and whether the final answer accurately reflected that result. Add a retry case and a revoked-permission case. A fluent answer about an asset that was never looked up must fail source-verification even when its wording sounds plausible.

A reliable trace connects request ID, principal, selected agent definition, discovered tool version, validated inputs and confirmed service response. Use the Converse response-parsing tests to recognize incomplete model streams before executing a tool. Keep operational signals distinct from private prompts; sensitive payloads should not be copied into broadly accessible dashboards. Use the Bedrock troubleshooting guide to diagnose HTTP errors, permissions and timeouts without widening privileges. The final exercise should identify one case where the correct behavior is to stop rather than keep using tools.

Create a reproducible release and teardown record

Finish with a one-page manifest naming the agent framework and version, supported MCP revision, gateway target or runtime endpoint, synthetic test dataset, IAM role scopes, maximum steps and observed denial cases. Include a rollback/disable path for the gateway target and a cleanup checklist for any temporary infrastructure. Document which tests used a mock backend and which actually reached AWS. Do not label an illustrated API shape as tested code when no authorized account call was made.

Map the experiment to the official AIP-C01 Domain 2 integration tasks: tool connectivity, model coordination, secure API patterns and safe failure. A candidate should be able to explain why a prompt instruction cannot grant IAM access, how a tool call is validated, and what evidence is needed before declaring an action complete. The AIP-C01 five-domain study map helps place this lab within professional exam readiness. Those skills remain useful even when agent-framework APIs evolve.