agents-connect

connect

通过 AgentCore Gateway 让你的 AgentCore Agent 访问外部 API、工具和服务，并使用 Cedar 策略控制其访问权限。

适用场景

• 你希望 Agent 调用外部 API 或 MCP 服务
• 你希望将 Lambda 函数作为 Agent 工具公开
• 你有想要转换为 Agent 工具的 OpenAPI 规范
• Agent 需要凭证才能调用外部服务
• 你希望限制 Agent 可以调用哪些工具（Cedar 策略）
• 你希望对工具调用实施基于角色或金额的访问控制
• Gateway 连接、工具调用或策略授权失败

如需添加 Cedar 策略来控制工具访问权限，请加载 references/policy.md。

输入

$ARGUMENTS 为可选项：

/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

流程

第 0 步：验证 CLI 版本

运行 agentcore --version。此技能要求版本为 v0.9.0 或更高版本。如果版本较旧，请告知开发者先运行 agentcore update。

第 1 步：阅读项目

阅读 agentcore/agentcore.json，了解：

• 项目使用的框架
• 已配置的 Gateway 和目标（位于 agentCoreGateways 数组中）

如果没有项目上下文： 询问他们想要连接什么，然后使用相应模式继续操作。

第 2 步：确定要连接的对象

询问（或根据 $ARGUMENTS 推断）：

“你想将 Agent 连接到什么？

1. 外部 MCP 服务（例如，第三方工具提供商）
2. 你编写的 Lambda 函数
3. 使用 OpenAPI 规范的 API
4. AWS API Gateway REST API
5. 没有 OpenAPI 规范、MCP 服务或 Lambda 作为前端的外部服务，而且你无法添加这些组件”

选项 1–4 会将服务接入为 Gateway 目标。 这是默认路径：Gateway 通过其凭证提供程序处理出站身份验证（因此 Agent 代码永远不会接触密钥），工具可通过 MCP 被发现，并且策略引擎可以在边缘授权或拒绝调用。请选择与服务相匹配的目标类型。

选项 5 是路径 D——注册凭证并从 Agent 代码直接调用 API。这是在无法实际接入 Gateway 时的备用方案；此技能会说明何时适用以及何时不适用。

---

默认情况：代码中优先使用 Gateway 目标，而不是直接调用 API

在讨论具体路径之前，先明确预期。大多数“我的 Agent 需要调用 X”这类需求，应该使用 Gateway 目标，而不是在入口点中使用 httpx。

Gateway 默认优先的原因：

• 在边缘注入凭证。 Gateway 的凭证提供方（OAuth、API key、IAM）会为出站请求附加身份验证信息。Agent 代码只需调用 session.call_tool(...)，完全不会接触密钥。若 Agent 代码使用 client = openai.OpenAI(api_key=...)，密钥就可能因提示词泄露、日志记录或回溯信息而被窃取。
• 可发现的工具目录。 工具由 MCP 服务列出；框架（Strands、LangGraph 等）会自动绑定这些工具。添加工具只需执行 agentcore add gateway-target 并重新部署，无需更改代码。
• 策略执行。 Cedar 策略可以按主体、工具和参数值授权或拒绝工具调用。如果工具调用隐藏在 Agent 代码中的 httpx.post(...) 里，就无法做到这一点。
• 语义搜索。 当目录中有 20 多个工具时，x_amz_bedrock_agentcore_search 会在每轮对话中选出相关工具。

适合在 Agent 代码中直接调用 API 的情况：

情况	Gateway 不适用的原因	应采取的做法
流式／双向协议（带实时输出的 SSE、WebSockets、WebRTC、长轮询）	Gateway 的 MCP 传输目前尚不能代理这些协议	直接调用，采用路径 D
延迟敏感的关键路径，且 MCP 跳转的耗时可以测量，并且已接受这一权衡	多一次网络跳转	直接调用，采用路径 D，并进行测量以支持该决策
供应商专有协议／二进制 SDK	没有可供 Gateway 代理的 HTTP 接口	直接使用供应商 SDK；如有密钥，则采用路径 D
通过 A2A 调用另一个 Agent	A2A 基于 HTTP 设计，且有自己的身份验证模型	使用 agents-build/references/multi-agent.md，而不是 Gateway 目标
运行时已有 IAM 权限的 AWS 服务 SDK（S3、DynamoDB、SQS 等）	代理这些服务没有身份验证方面的好处，反而会增加跳转	使用运行时的执行角色直接调用 boto3

其他所有情况都建议使用 Gateway 目标。如果开发者坚持直接调用，请询问上述五种情况中哪一种适用。如果都不适用，就引导他们改用 Gateway 目标。

分类判断规则：

• 服务有 MCP 服务 → 路径 A
• 服务是你控制的 Lambda 函数 → 路径 B
• 服务有 OpenAPI 规范（或者你可以生成一个——FastAPI、ASP.NET、Spring 等框架会自动生成 OpenAPI）→ 路径 C
• 服务已由 API Gateway 代理 → 路径 C（--type api-gateway）
• 以上都不适用，且你无法添加 → 路径 D

---

Gateway 是什么——又不是什么

在选择目标类型之前，先建立正确的认知。大多数对 Gateway 的困惑都源于把方向弄反了。

Gateway 为 Agent 托管供其调用的工具。 方向如下：

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

Agent 是客户端。Gateway 代理的是一个工具目录。每个工具都是一个 Gateway 目标（Lambda、OpenAPI、MCP 服务、API Gateway、Smithy）。

Gateway 不是用于接收对 Agent 调用的反向代理。 如果你正在构建的应用需要调用你的 Agent，该应用不应经过 Gateway。方向如下：

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

应用使用 IAM SigV4 为调用签名，或提供 JWT。应用端的集成模式请参见 agents-build/references/integrate.md。

当你不确定该选择哪种方向时

先问：是谁在调用谁？

• “我的 Agent 需要查询天气数据” → Agent 正在调用工具 → Gateway 目标（此技能，路径 A/B/C）
• “我的 FastAPI 应用需要调用我的 Agent” → 应用正在调用 Agent → 直接调用（不是 Gateway；请使用 agents-build/references/integrate.md）
• “我的 Agent 需要从我的 FastAPI 应用获取数据” → Agent 正在将应用作为工具调用 → Gateway 目标，将应用作为 OpenAPI 或 REST 目标公开（路径 C，使用你的 FastAPI 的 /openapi.json）

如果你发现自己配置的 Gateway 目标端点是 bedrock-agentcore.<region>.amazonaws.com，或指向你自己的运行时 URL，请停下来——你把调用流程弄反了。

哪种目标类型适合你的工具

工具类型	目标类型	说明
MCP 服务（第三方或自建）	mcp-server	MCP 工具目录中最常见
你编写的 AWS Lambda 函数	lambda-function-arn	自动使用 IAM 身份验证
带有 OpenAPI 规范的 HTTP API	open-api-schema	FastAPI 内置的 /openapi.json 即可使用
AWS API Gateway REST API	api-gateway	适用于已由 API Gateway 提供前置服务的 API
带有 Smithy 模型的 AWS 服务	smithy-model	直接集成 AWS 服务

如果你的工具没有现成的 OpenAPI 规范，而且既不是 MCP 服务，也不是 Lambda，该怎么办？可以将它封装到 Lambda 中（最简单），为它生成 OpenAPI 规范（FastAPI 会自动完成），或在它前面设置 API Gateway。

---

第 3 步：了解身份验证选项矩阵

这是最常见的错误来源。 身份验证选项取决于目标类型，而 CLI 仅提供 API/SDK 支持的部分选项。

连接目标	CLI --type	通过 CLI 配置出站身份验证	通过 API/SDK 提供的其他选项
外部 MCP 服务	mcp-server	none、oauth（仅限 2LO）	OAuth 3LO（AUTHORIZATION_CODE）；IAM（SigV4）
Lambda 函数	lambda-function-arn	none（默认值 — 通过网关角色直接调用）、oauth（2LO），用于受 OAuth 保护的下游服务	OAuth 3LO
OpenAPI 规范	open-api-schema	oauth（2LO）、api-key（必需 — 不支持 none）	OAuth 3LO
AWS API Gateway	api-gateway	none、api-key	IAM（GATEWAY_IAM_ROLE）
Smithy 模型	smithy-model	oauth（2LO）	IAM；OAuth 3LO

OAuth 有两种授权类型，而非一种。 CLI 的 --outbound-auth oauth 仅配置 双向 OAuth（客户端凭证 / M2M）。如果服务要求 三向 OAuth（AUTHORIZATION_CODE 授权类型，用户委托访问），则没有可用的 CLI 标志 — 必须通过 boto3 / AWS SDK 配置目标。有关 grantType: AUTHORIZATION_CODE 和 defaultReturnUrl 的 OAuthCredentialProvider，请参阅 CreateGatewayTarget 文档。3LO 适用于 MCP、Lambda、OpenAPI 和 Smithy 目标。请一开始就说明这一点 — 否则需要 3LO 的开发者会浪费一次来回，尝试使用并不存在的 CLI 标志。

MCP 服务的 IAM（SigV4） 需通过 AWS SDK/API 配置（使用 GATEWAY_IAM_ROLE 凭证提供方和 iamCredentialProvider.service 调用 CreateGatewayTarget），而非通过 CLI 配置。MCP 服务必须托管在原生验证 SigV4 的 AWS 服务后面：AgentCore Runtime、AgentCore Gateway、Amazon API Gateway 或 Lambda 函数 URL。ALB 或直接连接 EC2 的端点不会验证 SigV4 — 此类场景应改用 OAuth。（MCP 服务目标身份验证策略）

API 层不支持对 MCP 服务目标使用 API 密钥身份验证 — 这不只是 CLI 的限制。MCP 服务目标文档列出的 MCP 目标支持的身份验证策略只有“无授权、OAuth 和 IAM”。如果 MCP 服务使用 API 密钥（第三方 MCP 提供商常见的模式），请通过路径 D 在 Agent 代码中处理。

身份验证选项会变化。 如果上面的矩阵与 CLI 接受的选项不符，请查看当前 CLI 帮助（agentcore add gateway-target --help）和 AWS 文档 — 不同目标类型的身份验证支持情况会随版本更新而变化。如果有可用的 awsknowledge MCP 服务，请搜索“AgentCore CreateGatewayTarget”以获取当前 API 参数。

网关身份验证：CLI 与 API 的区别： CLI 支持 none、oauth（2LO）和 api-key。如需配置 IAM（SigV4）和三向 OAuth，请直接使用 boto3 — 示例见下方的路径 A 部分。通用做法是：通过 CLI 创建网关和目标并进行部署，然后在 CLI 不支持高级身份验证配置时，通过 boto3 应用该配置。

在生成任何命令之前，请先告知开发者其目标类型适用哪种身份验证选项。

当网关拥有许多工具时，让模型搜索这些工具

当网关的工具数量超过少数几个（大约 20 个以上）时，每轮都向模型传递所有工具定义会浪费令牌并降低准确性。模型只看到与当前请求相关的工具时，效果会更好。

AgentCore Gateway 内置了语义搜索工具，正是为此而设。你的 Agent 会调用一个名为 x_amz_bedrock_agentcore_search 的 MCP 工具，并提供自然语言查询；网关随后会从其目录中返回最相关的工具。接着，Agent 就能像平常一样调用返回的工具。

如果开发者正在考虑使用 Bedrock Knowledge Bases、向量存储或自定义嵌入来构建自己的工具选择层，请让他们打住。网关已经具备此功能，并且已根据经过整理的相关性标准完成评估，无需管理任何基础设施。

使用模式（Agent 调用此工具的方式与调用任何其他网关工具相同）：

# Via the MCP client, as a tool call
result = await session.call_tool(
    "x_amz_bedrock_agentcore_search",
    arguments={"query": "find tools related to processing refunds"}
)
# result.content lists the most relevant tools — the agent then invokes them

此功能适用于任何目标类型（Lambda、OpenAPI、MCP、API Gateway、Smithy）。可按网关启用此功能；具体 API 接口和针对特定框架的客户端代码，请参阅在 AgentCore 网关中搜索工具文档。

经验法则：如果网关拥有 20 个以上的工具，建议启用语义搜索。对于较小的目录，直接传递所有工具仍然可行。

将调用方的自定义标头传递给 Agent

如果开发者需要调用方发送自定义 HTTP 标头（租户 ID、关联 ID、协议专用标头，例如 A2A-Version、跟踪标头、幂等键），运行时的默认行为是在这些标头到达 Agent 代码前剥离大部分标头。加载 agents-build/references/request-headers.md，了解允许列表配置和前缀模式。

这涉及发往 Agent 的入站调用，而非发往工具的出站调用，不过开发者经常会遇到这个问题，因此值得在此提及。

---

路径 A：MCP 服务

添加网关（如果尚不存在）

警告

绝不要在生产环境中部署未启用入站身份验证的网关。没有授权器的网关会向任何知道 URL 的调用方公开所有已连接的工具（Lambda、MCP、OpenAPI）——其效果等同于在运行时使用 --authorizer-type NONE。 生产环境中的网关始终应使用 --authorizer-type CUSTOM_JWT 或 AWS_IAM。 无身份验证的形式（agentcore add gateway --name X）仅用于本地测试。

# Development (no inbound auth — for testing only)
agentcore add gateway --name MyGateway

# Production (JWT inbound auth)
agentcore add gateway \
  --name MyGateway \
  --authorizer-type CUSTOM_JWT \
  --discovery-url https://your-idp.example.com/.well-known/openid-configuration \
  --allowed-audience my-api \
  --allowed-clients my-client-id

将 MCP 服务添加为目标

# No outbound auth (public MCP server)
agentcore add gateway-target \
  --type mcp-server \
  --name WeatherTools \
  --endpoint https://mcp.example.com/mcp \
  --gateway MyGateway

# OAuth outbound auth (2-legged — client credentials / M2M)
agentcore add gateway-target \
  --type mcp-server \
  --name WeatherTools \
  --endpoint https://mcp.example.com/mcp \
  --gateway MyGateway \
  --outbound-auth oauth \
  --oauth-client-id your-client-id \
  --oauth-client-secret your-client-secret \
  --oauth-discovery-url https://auth.example.com/.well-known/openid-configuration \
  --oauth-scopes read,write

注意：CLI 的 --outbound-auth 标志支持 MCP 服务使用 oauth（2LO / 客户端凭证）或 none。

• 三方 OAuth（AUTHORIZATION_CODE 授权类型）——用户委托访问——受 API 支持，但 CLI 不提供此路径。请使用 boto3 create_gateway_target 配置 OAuthCredentialProvider.grantType = "AUTHORIZATION_CODE" 和 defaultReturnUrl。请参阅使用 Authorization Code 流连接到受 OAuth 保护的 MCP 服务。
• MCP 服务的 IAM（SigV4）（托管在 AgentCore Runtime、另一个 AgentCore Gateway、API Gateway 或 Lambda Function URLs 上）需通过 AWS SDK/API 配置（而非 CLI）——请使用 CreateGatewayTarget，并配置 GATEWAY_IAM_ROLE 凭证提供方及 iamCredentialProvider.service 值。
• API 密钥身份验证在 API 层面不受 MCP 服务目标支持（MCP 目标文档仅列出无身份验证、OAuth 和 IAM 这几种策略）——如果 MCP 服务使用 API 密钥，请直接在 Agent 代码中处理（参见路径 D）。

部署并获取网关 URL

agentcore deploy -y
agentcore fetch access --name MyGateway

部署后，网关 URL 会注入为 AGENTCORE_GATEWAY_<NAME>_URL。

生成网关客户端代码

与框架无关的 MCP 客户端：

import os
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

# Injected by AgentCore after deploy. Format: AGENTCORE_GATEWAY_<UPPERCASENAME>_URL
GATEWAY_URL = os.getenv("AGENTCORE_GATEWAY_MYGATEWAY_URL")

async def get_gateway_tools():
    """Discover tools from the gateway. Returns empty list if not deployed."""
    if not GATEWAY_URL:
        return []
    async with streamablehttp_client(GATEWAY_URL) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.list_tools()
            return result.tools

async def call_gateway_tool(tool_name: str, arguments: dict):
    """Call a specific tool through the gateway."""
    if not GATEWAY_URL:
        raise RuntimeError("Gateway not available in local dev — deploy first")
    async with streamablehttp_client(GATEWAY_URL) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            return await session.call_tool(tool_name, arguments)

对于 Strands，将网关工具直接传递给 Agent：

from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession
from strands import Agent
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from model.load import load_model  # scaffolded by `agentcore create`

app = BedrockAgentCoreApp()
GATEWAY_URL = os.getenv("AGENTCORE_GATEWAY_MYGATEWAY_URL")

@app.entrypoint
def invoke(payload, context):
    if not GATEWAY_URL:
        # Local dev — run without gateway tools
        agent = Agent(model=load_model())
        return {"response": str(agent(payload.get("prompt", "")))}

    # Deployed — discover and use gateway tools
    tools = asyncio.run(get_gateway_tools())
    agent = Agent(
        model=load_model(),
        tools=tools,
    )
    return {"response": str(agent(payload.get("prompt", "")))}

if __name__ == "__main__":
    app.run()

对于 LangGraph，将网关工具添加到工具节点：

from langchain_mcp_adapters.client import MultiServerMCPClient

@app.entrypoint
def agent_invocation(payload, context):
    if not GATEWAY_URL:
        tools = []
    else:
        # Use LangChain MCP adapter to get tools as LangChain-compatible tools
        client = MultiServerMCPClient({"gateway": {"url": GATEWAY_URL, "transport": "streamable_http"}})
        tools = asyncio.run(client.get_tools())

    llm_with_tools = llm.bind_tools(tools)
    # ... rest of your LangGraph graph ...

---

路径 B：将 Lambda 函数用作工具

agentcore add gateway-target \
  --type lambda-function-arn \
  --name MyTools \
  --lambda-arn arn:aws:lambda:us-east-1:123456789012:function:my-tools \
  --tool-schema-file tools.json \
  --gateway MyGateway

tools.json 定义工具架构：

{
  "inlinePayload": [
    {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": {"type": "string", "description": "City name"}
        },
        "required": ["city"]
      }
    }
  ]
}

身份验证： Lambda 目标会自动使用 IAM 角色身份验证——无需 --outbound-auth 标志。网关的执行角色需要对 Lambda ARN 具有 lambda:InvokeFunction 权限。

使用与路径 A 相同的 MCP 客户端代码调用工具。

---

路径 C：将 OpenAPI 规范用作工具

# From a local file (api-key auth)
agentcore add credential --name MyAPIKey --api-key sk-...

agentcore add gateway-target \
  --type open-api-schema \
  --name MyAPI \
  --schema specs/api.json \
  --gateway MyGateway \
  --outbound-auth api-key \
  --credential-name MyAPIKey

OpenAPI 目标必须进行身份验证——使用 oauth（客户端凭证或授权码）或 api-key。

⚠️ 安全提示： --api-key 会出现在 shell 历史记录中。有两个更安全的选项：

1. 交互式提示（推荐）： 运行 agentcore add credential --name MyAPIKey --type api-key，不要加上 --api-key——CLI 会提示你输入，值会直接传入凭证提供程序（由 Secrets Manager 提供支持），不会进入 shell 历史记录。
2. 仅限本地开发时编辑 agentcore.json + .env.local： 如果需要凭证在 agentcore dev 下生效，请将值放入 agentcore/.env.local（已加入 gitignore）。此文件仅供本地开发服务器读取——部署时不会上传到运行时。部署后的运行时会从凭证提供程序获取值。

不要尝试通过环境变量向部署后的运行时传递凭证——AgentCore Runtime 环境变量不由保险库提供支持。使用 agentcore add credential 注册一次凭证，并在网关目标或代码中通过名称引用（路径 D）。

---

路径 D：在 Agent 代码中使用凭证

用于在 Agent 代码中直接调用 API（而不是通过网关目标调用）。

选择路径 D 前，请先确认它是否真的是正确的路径

路径 D 是备用方案，而非首选方案。对于大多数外部服务，网关目标（路径 A–C）更安全，所需代码也更少。生成路径 D 代码前，请确认符合以下情况之一：

• 服务使用网关无法代理的流式／双向协议（带实时输出的 SSE、WebSockets、WebRTC）
• 这是一个经测量确实对延迟敏感的关键路径，且团队已接受这种权衡
• 客户端是没有 HTTP 接口的供应商二进制 SDK
• 这是一个 AWS 服务 SDK，运行时的执行角色已具有 IAM 权限（这种情况下：直接使用 SDK，无需注册凭证）
• 开发者遇到了具体的阻碍（例如，服务提供的是 OpenAI 风格 API，而供应商 SDK 对其进行了封装；将 SDK 调用改为网关目标会导致功能退化）

如果以上情况都不适用，请返回路径 A/B/C：

“在为 Agent 代码直接使用注册凭证之前，我们能否改用网关目标来代理此服务？网关会在边缘注入凭证——Agent 代码无需接触密钥——而且工具可以受策略管控。如果 SERVICE 提供 OpenAPI 规范、MCP 服务或 Lambda 函数来代理它，路径 C / A / B 会更合适。哪种情况适用？”

只有在开发者确认网关确实无法使用且理由充分后，才继续阅读路径 D 的其余内容。

注册凭证

# API key
agentcore add credential --name OpenAI --api-key sk-...

# OAuth (machine-to-machine)
agentcore add credential \
  --name MyOAuthProvider \
  --type oauth \
  --discovery-url https://idp.example.com/.well-known/openid-configuration \
  --client-id my-client-id \
  --client-secret my-client-secret \
  --scopes read,write

⚠️ 安全提示： --api-key 和 --client-secret 会出现在 shell 历史记录中。运行命令时不要带上这些标志，这样就会显示交互式提示——值会直接传入凭证提供程序，不会进入 shell 历史记录。

仅限本地开发时，将相同的值放入 agentcore/.env.local（已加入 gitignore），以便 agentcore dev 在本地解析装饰器。部署后的运行时会忽略 .env.local，并在调用时从凭证提供程序获取密钥——切勿将密钥作为运行时环境变量传递。

在 Agent 代码中使用凭证

使用 @requires_api_key 或 @requires_access_token 装饰器——它们会自动处理令牌缓存和刷新。这些装饰器适用于同步和异步函数：

from bedrock_agentcore.identity.auth import requires_api_key, requires_access_token

# Sync function — decorator injects the fetched key via keyword arg
@requires_api_key(provider_name="OpenAI")
def call_openai(prompt: str, *, api_key: str) -> str:
    import openai
    client = openai.OpenAI(api_key=api_key)
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

# Async function — same decorator, async def
@requires_access_token(
    provider_name="MyOAuthProvider",
    scopes=["read", "write"],
    auth_flow="M2M",
)
async def call_my_api(data: dict, *, access_token: str) -> dict:
    import httpx
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.example.com/endpoint",
            headers={"Authorization": f"Bearer {access_token}"},
            json=data,
        )
        return response.json()

装饰器本身会处理令牌生命周期——无需仅为了使用它而将函数设为异步。参数仅限关键字参数（*, api_key: str 或 *, access_token: str）——装饰器会注入这些参数。

本地开发： 在 agentcore dev 中，凭证从 agentcore/.env.local 读取。在本地和部署环境中，装饰器模式的用法相同。

---

本地开发的限制

警告

Gateway URL（AGENTCORE_GATEWAY_*_URL）仅在部署后可用。 在 agentcore dev 中，不会设置这些环境变量。使用前务必检查：

GATEWAY_URL = os.getenv("AGENTCORE_GATEWAY_MYGATEWAY_URL")
if not GATEWAY_URL:
    # run without gateway tools in local dev

切勿假定 Gateway 在本地可用。

---

故障排除

“mcp-server target 不支持 api-key 身份验证” 没错——在 API 层面，MCP 服务目标不支持 API 密钥身份验证（MCP 目标身份验证策略）。可选方案：OAuth（2LO 或 3LO）、IAM（适用于托管在 AgentCore Runtime、API Gateway 或 Lambda Function URL 上的 MCP 服务），或路径 D——在 Agent 代码中管理凭证，并直接调用 MCP 服务。

“我需要 3LO / 授权码 OAuth，但 --outbound-auth oauth 没有询问返回 URL” CLI 仅配置 2LO（客户端凭证）。3-legged OAuth 需要使用 boto3——调用 create_gateway_target，并设置 credentialProviderType: OAUTH、grantType: AUTHORIZATION_CODE 和 defaultReturnUrl。请参阅使用授权码流程连接受 OAuth 保护的 MCP 服务。

“api-gateway target 不支持 oauth” 对于 API Gateway 目标，请使用 api-key 或 none。

部署后未设置 Gateway URL 运行 agentcore fetch access --name MyGateway 获取 URL。运行 agentcore status --type gateway，确认 Gateway 已部署。

工具调用因身份验证错误而失败 运行 agentcore logs --runtime MyAgent --since 1h --level error，查看具体错误。常见原因：OAuth 令牌过期、凭证名称错误、缺少 IAM 权限。

“将 Gateway 添加到现有 Agent”的变通方法 CLI 建议创建一个临时 Agent，以便复制 Gateway 客户端代码。本技能会直接生成代码，无需变通方法。

MCP 客户端（Claude Desktop、claude.ai）无法自动连接到 Gateway AgentCore Gateway 目前尚未实现 MCP OAuth 规范端点（RFC 8414 OAuth Authorization Server Metadata、RFC 7591 Dynamic Client Registration）。需要自动发现 OAuth 配置并自行注册的 MCP 客户端（例如 Claude Desktop 和 claude.ai），如果没有手动配置凭证，就无法连接。变通方法是手动获取 Cognito client_id 和 client_secret，并在 MCP 客户端的高级设置中输入。这是平台限制，不是配置错误。

输出

• 明确建议选择 Gateway 目标还是直接调用 API，并以直接调用合理的五种情况为依据
• 用于设置 Gateway 和目标的 CLI 命令（如果路径 D 更合适，则提供注册凭证的命令）
• 特定框架的 Gateway 客户端代码
• 凭证设置（避免凭证暴露在 shell 历史记录中，绝不将凭证存储在运行时环境变量中）
• 本地开发限制的处理方式