agents-connect

What this skill does

# connect

Give your AgentCore agent access to external APIs, tools, and services via the AgentCore Gateway — and control what it can access with Cedar policies.

## When to use

- You want your agent to call an external API or MCP server
- You want to expose Lambda functions as agent tools
- You have an OpenAPI spec you want to turn into agent tools
- Your agent needs credentials to call an external service
- You want to restrict which tools your agent can call (Cedar policies)
- You want role-based or amount-based access control on tool calls
- A gateway connection, tool call, or policy authorization is failing

For adding Cedar policies to control tool access, load [`references/policy.md`](references/policy.md).

## Input

`$ARGUMENTS` is optional:

```
/connect                    # interactive — asks what you're connecting to
/connect mcp                # MCP server setup
/connect lambda             # Lambda function as tools
/connect openapi            # OpenAPI schema as tools
/connect credential         # Add a credential for outbound auth
```

## Process

### Step 0: Verify CLI version

Run `agentcore --version`. This skill requires v0.9.0 or later. If the version is older, tell the developer to run `agentcore update` before proceeding.

### Step 1: Read the project

Read `agentcore/agentcore.json` to understand:

- What framework the project uses
- What gateways and targets are already configured (in the `agentCoreGateways` array)

**If no project context:** Ask what they're trying to connect to and proceed with the appropriate pattern.

### Step 2: Identify what they're connecting to

Ask (or infer from `$ARGUMENTS`):

> "What are you connecting your agent to?
>
> 1. An external MCP server (e.g., a third-party tool provider)
> 2. A Lambda function you've written
> 3. An API with an OpenAPI spec
> 4. An AWS API Gateway REST API
> 5. An external service with no OpenAPI spec, MCP server, or Lambda in front of it — and you can't add one"

**Options 1–4 front the service as a Gateway target.** This is the default path: the gateway handles outbound auth via its credential providers (so the agent code never sees the secret), the tool becomes discoverable over MCP, and policy engines can authorize or deny calls at the edge. Pick the target type that matches the service.

**Option 5 is Path D** — register a credential and call the API directly from agent code. This is the fallback when fronting isn't practical; the skill walks through when it's appropriate and when it isn't.

---

## Default: prefer a Gateway target over direct API calls in code

Before jumping into paths, set expectations. Most "my agent needs to call X" requests land on a Gateway target — not on `httpx` inside the entrypoint.

**Why Gateway is the default:**

- **Credential injection at the edge.** Gateway's credential providers (OAuth, API key, IAM) attach auth to the outbound request. The agent code calls `session.call_tool(...)` — it never touches the secret. Agent code that does `client = openai.OpenAI(api_key=...)` is one leaked prompt / log line / traceback away from exfiltrating the key.
- **Discoverable tool catalog.** Tools are listed by the MCP server; the framework (Strands, LangGraph, etc.) binds them automatically. Adding a tool is an `agentcore add gateway-target` + redeploy, not a code change.
- **Policy enforcement.** Cedar policies can authorize or deny tool calls per principal, per tool, per argument value. This is impossible when tool calls are buried in `httpx.post(...)` inside agent code.
- **Semantic search.** Once the catalog has 20+ tools, `x_amz_bedrock_agentcore_search` selects the relevant ones per turn.

**When a direct API call in agent code is the right answer:**

| Situation | Why Gateway isn't right | What to do |
|---|---|---|
| Streaming/bidirectional protocol (SSE with live output, WebSockets, WebRTC, long-polling) | Gateway's MCP transport doesn't front those yet | Direct call, Path D |
| Latency hot path where the MCP hop is measurable and the trade-off is accepted | Extra network hop | Direct call, Path D, with measurement to back the decision |
| Vendor proprietary protocol / binary SDK | No HTTP surface for Gateway to front | Use the vendor SDK directly, Path D for any secrets |
| Calling another agent via A2A | A2A is HTTP-by-design and has its own auth model | [`agents-build/references/multi-agent.md`](../agents-build/references/multi-agent.md), not a Gateway target |
| AWS service SDK (S3, DynamoDB, SQS, etc.) the runtime already has IAM for | No auth value in fronting — adds hops | Direct boto3 call with the runtime's execution role |

For **every other case**, recommend a Gateway target. If the developer insists on a direct call, ask which of the five situations above applies. If none, steer them back to a Gateway target.

**Triage heuristic:**

- Service has an MCP server → Path A
- Service is a Lambda function you control → Path B
- Service has an OpenAPI spec (or you can generate one — FastAPI, ASP.NET, Spring, etc. generate OpenAPI automatically) → Path C
- Service is already fronted by API Gateway → Path C (`--type api-gateway`)
- None of the above and you can't add one → Path D

---

## What Gateway is — and what it isn't

Before choosing a target type, get the mental model right. Most Gateway confusion comes from having it flipped.

**Gateway hosts tools for your agent to call.** The direction is:

```
Your agent  ───→  Gateway  ───→  Lambda function / OpenAPI API / MCP server / Smithy model
             (agent calls tool)
```

The agent is the client. The Gateway fronts a catalog of tools. Each tool is a Gateway target (Lambda, OpenAPI, MCP server, API Gateway, Smithy).

**Gateway is not an inbound reverse proxy for your agent.** If you're building an app that needs to invoke your agent, the app does not go through a Gateway. The direction is:

```
Your app  ───→  AgentCore Runtime  (direct invoke_agent_runtime call)
```

The app signs the invocation with IAM SigV4 or presents a JWT. See [`agents-build/references/integrate.md`](../agents-build/references/integrate.md) for the app-side patterns.

### When you're confused about which direction you need

Ask: **who is calling whom?**

- "My agent needs to look up weather data" → agent is calling a tool → **Gateway target** (this skill, Paths A/B/C)
- "My FastAPI app needs to call my agent" → app is calling the agent → **direct invocation** (not Gateway; use [`agents-build/references/integrate.md`](../agents-build/references/integrate.md))
- "My agent needs to fetch data from my FastAPI app" → agent is calling the app as a tool → **Gateway target** with the app exposed as an OpenAPI or REST target (Path C with your FastAPI's `/openapi.json`)

If you catch yourself configuring a Gateway target whose endpoint is `bedrock-agentcore.<region>.amazonaws.com` or pointing at your own runtime's URL, stop — you have the flow inverted.

### What target type fits your tool

| What the tool is | Target type | Notes |
|---|---|---|
| MCP server (third-party or your own) | `mcp-server` | Most common for MCP tool catalogs |
| AWS Lambda function you wrote | `lambda-function-arn` | Uses IAM auth automatically |
| HTTP API with an OpenAPI spec | `open-api-schema` | FastAPI's built-in `/openapi.json` works |
| AWS API Gateway REST API | `api-gateway` | For APIs already fronted by API Gateway |
| AWS service with a Smithy model | `smithy-model` | Direct AWS service integration |

Your tool doesn't naturally have an OpenAPI spec and isn't an MCP server or Lambda? Either wrap it in a Lambda (simplest), generate an OpenAPI spec for it (FastAPI does this automatically), or front it with API Gateway.

---

### Step 3: Navigate the auth matrix

**This is the most common source of errors.** The auth options depend on the target type, and the CLI exposes only a subset of what the API/SDK support.

| What you're connecting to | CLI `--type` | Outbound auth via CLI | Additional options via API/SDK |
|---|---|