Skip to content

docs: add gateway documentation for commands, configuration, and local development #474

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aidandaly24 merged 1 commit into from
Mar 2, 2026
+499 −15
Merged

docs: add gateway documentation for commands, configuration, and local development #474

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@ Projects use JSON schema files in the `agentcore/` directory:
- [CLI Commands Reference](docs/commands.md) - Full command reference for scripting and CI/CD
- [Configuration](docs/configuration.md) - Schema reference for config files
- [Frameworks](docs/frameworks.md) - Supported frameworks and model providers
- [Gateway](docs/gateway.md) - Gateway setup, targets, and authentication
- [Memory](docs/memory.md) - Memory strategies and sharing
- [Local Development](docs/local-development.md) - Dev server and debugging

Expand Down
119 changes: 113 additions & 6 deletions docs/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,21 +151,114 @@ agentcore add memory \
| `--expiry <days>` | Event expiry (default: 30) |
| `--json` | JSON output |

### add gateway

Add a gateway to the project. Gateways act as MCP-compatible proxies that route agent requests to backend tools.

```bash
# Interactive mode (select 'Gateway' from the menu)
agentcore add

# No authorization (development/testing)
agentcore add gateway --name MyGateway

# CUSTOM_JWT authorization (production)
agentcore add gateway \
--name MyGateway \
--authorizer-type CUSTOM_JWT \
--discovery-url https://idp.example.com/.well-known/openid-configuration \
--allowed-audience my-api \
--allowed-clients my-client-id \
--agent-client-id agent-client-id \
--agent-client-secret agent-client-secret
```

| Flag | Description |
| -------------------------------- | ------------------------------------------------------------ |
| `--name <name>` | Gateway name |
| `--description <desc>` | Gateway description |
| `--authorizer-type <type>` | `NONE` (default) or `CUSTOM_JWT` |
| `--discovery-url <url>` | OIDC discovery URL (required for CUSTOM_JWT) |
| `--allowed-audience <values>` | Comma-separated allowed audiences (required for CUSTOM_JWT) |
| `--allowed-clients <values>` | Comma-separated allowed client IDs (required for CUSTOM_JWT) |
| `--allowed-scopes <scopes>` | Comma-separated allowed scopes (optional for CUSTOM_JWT) |
| `--agent-client-id <id>` | Agent OAuth client ID for Bearer token auth (CUSTOM_JWT) |
| `--agent-client-secret <secret>` | Agent OAuth client secret (CUSTOM_JWT) |
| `--json` | JSON output |

### add gateway-target

Add a gateway target to the project. Targets are backend tools exposed through a gateway as an external MCP server
endpoint.

```bash
# Interactive mode (select 'Gateway Target' from the menu)
agentcore add

# External MCP server endpoint
agentcore add gateway-target \
--name WeatherTools \
--source existing-endpoint \
--endpoint https://mcp.example.com/mcp \
--gateway MyGateway

# External endpoint with OAuth outbound auth
agentcore add gateway-target \
--name SecureTools \
--source existing-endpoint \
--endpoint https://api.example.com/mcp \
--gateway MyGateway \
--outbound-auth oauth \
--oauth-client-id my-client \
--oauth-client-secret my-secret \
--oauth-discovery-url https://auth.example.com/.well-known/openid-configuration
```

| Flag | Description |
| -------------------------------- | ----------------------------------------------- |
| `--name <name>` | Target name |
| `--description <desc>` | Target description |
| `--source <source>` | `existing-endpoint` |
| `--endpoint <url>` | MCP server endpoint URL |
| `--gateway <name>` | Gateway to attach target to |
| `--outbound-auth <type>` | `oauth`, `api-key`, or `none` |
| `--credential-name <name>` | Existing credential name for outbound auth |
| `--oauth-client-id <id>` | OAuth client ID (creates credential inline) |
| `--oauth-client-secret <secret>` | OAuth client secret (creates credential inline) |
| `--oauth-discovery-url <url>` | OAuth discovery URL (creates credential inline) |
| `--oauth-scopes <scopes>` | OAuth scopes, comma-separated |
| `--json` | JSON output |

### add identity

Add a credential provider (API key). Credentials are top-level resources in the flat resource model.
Add a credential to the project. Supports API key and OAuth credential types.

```bash
# API key credential
agentcore add identity \
--name OpenAI \
--api-key sk-...

# OAuth credential
agentcore add identity \
--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
```

| Flag | Description |
| ----------------- | --------------- |
| `--name <name>` | Credential name |
| `--api-key <key>` | API key value |
| `--json` | JSON output |
| Flag | Description |
| -------------------------- | -------------------------------- |
| `--name <name>` | Credential name |
| `--type <type>` | `api-key` (default) or `oauth` |
| `--api-key <key>` | API key value (api-key type) |
| `--discovery-url <url>` | OAuth discovery URL (oauth type) |
| `--client-id <id>` | OAuth client ID (oauth type) |
| `--client-secret <secret>` | OAuth client secret (oauth type) |
| `--scopes <scopes>` | OAuth scopes, comma-separated |
| `--json` | JSON output |

### remove

Expand All @@ -175,6 +268,8 @@ Remove resources from project.
agentcore remove agent --name MyAgent --force
agentcore remove memory --name SharedMemory
agentcore remove identity --name OpenAI
agentcore remove gateway --name MyGateway
agentcore remove gateway-target --name WeatherTools

# Reset everything
agentcore remove all --force
Expand Down Expand Up @@ -281,6 +376,18 @@ agentcore add memory --name SharedMemory --strategies SEMANTIC
agentcore deploy -y
```

### Gateway Setup

```bash
agentcore add gateway --name MyGateway
agentcore add gateway-target \
--name WeatherTools \
--source existing-endpoint \
--endpoint https://mcp.example.com/mcp \
--gateway MyGateway
agentcore deploy -y
```

### JSON Output for Automation

All commands with `--json` output structured data:
Expand Down
158 changes: 154 additions & 4 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ AgentCore projects use JSON configuration files in the `agentcore/` directory.
| File | Purpose |
| --------------------- | ------------------------------------------- |
| `agentcore.json` | Project, agents, memories, and credentials |
| `mcp.json` | Gateways, gateway targets, and MCP tools |
| `aws-targets.json` | Deployment targets |
| `deployed-state.json` | Runtime state (auto-managed, do not edit) |
| `.env.local` | API keys for local development (gitignored) |
Expand Down Expand Up @@ -43,6 +44,12 @@ Main project configuration using a **flat resource model**. Agents, memories, an
{
"type": "ApiKeyCredentialProvider",
"name": "OpenAI"
},
{
"type": "OAuthCredentialProvider",
"name": "MyOAuthProvider",
"discoveryUrl": "https://idp.example.com/.well-known/openid-configuration",
"scopes": ["read", "write"]
}
]
}
Expand All @@ -56,7 +63,9 @@ Main project configuration using a **flat resource model**. Agents, memories, an
| `version` | Yes | Schema version (integer, currently `1`) |
| `agents` | Yes | Array of agent specifications |
| `memories` | Yes | Array of memory resources |
| `credentials` | Yes | Array of credential providers |
| `credentials` | Yes | Array of credential providers (API key or OAuth) |

> Gateway configuration is stored separately in `mcp.json`. See [mcp.json](#mcpjson) below.

---

Expand Down Expand Up @@ -142,6 +151,8 @@ Strategy configuration:

## Credential Resource

### API Key Credential

```json
{
"type": "ApiKeyCredentialProvider",
Expand All @@ -154,8 +165,142 @@ Strategy configuration:
| `type` | Yes | Always `"ApiKeyCredentialProvider"` |
| `name` | Yes | Credential name (3-255 chars) |

The actual API key is stored in `.env.local` for local development and in AgentCore Identity service for deployed
environments.
### OAuth Credential

```json
{
"type": "OAuthCredentialProvider",
"name": "MyOAuthProvider",
"discoveryUrl": "https://idp.example.com/.well-known/openid-configuration",
"scopes": ["read", "write"]
}
```

| Field | Required | Description |
| -------------- | -------- | ------------------------------------------------------ |
| `type` | Yes | Always `"OAuthCredentialProvider"` |
| `name` | Yes | Credential name (3-255 chars) |
| `discoveryUrl` | Yes | OIDC discovery URL (must be a valid URL) |
| `scopes` | No | Array of OAuth scopes |
| `vendor` | No | Credential provider vendor (default: `"CustomOauth2"`) |
| `managed` | No | Whether auto-created by the CLI (do not edit) |
| `usage` | No | `"inbound"` or `"outbound"` |

The actual secrets (API keys, client IDs, client secrets) are stored in `.env.local` for local development and in
AgentCore Identity service for deployed environments.

---

## mcp.json

Gateway and MCP tool configuration. Gateways, their targets, and standalone MCP runtime tools are defined here.

```json
{
"agentCoreGateways": [
{
"name": "MyGateway",
"description": "My gateway",
"authorizerType": "NONE",
"targets": [
{
"name": "WeatherTools",
"targetType": "mcpServer",
"endpoint": "https://mcp.example.com/mcp"
}
]
}
],
"unassignedTargets": []
}
```

### Top-Level Fields

| Field | Required | Description |
| ------------------- | -------- | ------------------------------------- |
| `agentCoreGateways` | Yes | Array of gateway definitions |
| `unassignedTargets` | No | Targets not yet assigned to a gateway |

### Gateway

| Field | Required | Description |
| ------------------------- | -------- | ------------------------------------------------------------ |
| `name` | Yes | Gateway name (alphanumeric, hyphens, 1-63 chars) |
| `description` | No | Gateway description |
| `targets` | Yes | Array of gateway targets |
| `authorizerType` | No | `"NONE"` (default), `"AWS_IAM"`, or `"CUSTOM_JWT"` |
| `authorizerConfiguration` | No | Required when `authorizerType` is `"CUSTOM_JWT"` (see below) |

### CUSTOM_JWT Authorizer Configuration

```json
{
"authorizerType": "CUSTOM_JWT",
"authorizerConfiguration": {
"customJwtAuthorizer": {
"discoveryUrl": "https://idp.example.com/.well-known/openid-configuration",
"allowedAudience": ["my-api"],
"allowedClients": ["my-client-id"],
"allowedScopes": ["read", "write"]
}
}
}
```

| Field | Required | Description |
| ----------------- | -------- | ---------------------------------------------------------------------- |
| `discoveryUrl` | Yes | OIDC discovery URL (must end with `/.well-known/openid-configuration`) |
| `allowedAudience` | Yes | Array of allowed audience values |
| `allowedClients` | Yes | Array of allowed client IDs (at least 1) |
| `allowedScopes` | No | Array of allowed scopes |

### Gateway Target

A target is a backend tool exposed through a gateway. Targets can be external MCP server endpoints or compute-backed
implementations.

**External MCP server endpoint:**

```json
{
"name": "WeatherTools",
"targetType": "mcpServer",
"endpoint": "https://mcp.example.com/mcp"
}
```

**External endpoint with outbound auth:**

```json
{
"name": "SecureTools",
"targetType": "mcpServer",
"endpoint": "https://api.example.com/mcp",
"outboundAuth": {
"type": "OAUTH",
"credentialName": "MyOAuthProvider",
"scopes": ["tools:read"]
}
}
```

| Field | Required | Description |
| ----------------- | -------- | -------------------------------------------------------------------- |
| `name` | Yes | Target name |
| `targetType` | Yes | `"mcpServer"` or `"lambda"` |
| `endpoint` | Cond. | MCP server URL (required for external `mcpServer` targets) |
| `compute` | Cond. | Compute configuration (required for `lambda` and scaffolded targets) |
| `toolDefinitions` | Cond. | Array of tool definitions (required for `lambda` targets) |
| `outboundAuth` | No | Outbound authentication configuration |

### Outbound Auth

| Field | Required | Description |
| ---------------- | -------- | ---------------------------------------------------- |
| `type` | Yes | `"OAUTH"`, `"API_KEY"`, or `"NONE"` (default) |
| `credentialName` | Cond. | Credential name (required when type is not `"NONE"`) |
| `scopes` | No | OAuth scopes (for `"OAUTH"` type) |

---

Expand Down Expand Up @@ -190,12 +335,17 @@ current list.

## .env.local

API keys for local development. This file is gitignored.
Secrets for local development. This file is gitignored.

```bash
# API key credentials
AGENTCORE_CREDENTIAL_{projectName}OPENAI=sk-...
AGENTCORE_CREDENTIAL_{projectName}ANTHROPIC=sk-ant-...
AGENTCORE_CREDENTIAL_{projectName}GEMINI=...

# OAuth credentials
AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_ID=my-client-id
AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_SECRET=my-client-secret
```

Environment variable names should match the credential names in your configuration.
Loading
Loading