diff --git a/aws-transform-agent-toolkit/steering/agent-registration.md b/aws-transform-agent-toolkit/steering/agent-registration.md index 8f93a08..383e6ee 100644 --- a/aws-transform-agent-toolkit/steering/agent-registration.md +++ b/aws-transform-agent-toolkit/steering/agent-registration.md @@ -53,6 +53,29 @@ client = boto3.client( **NEVER omit the endpoint URL** — without it, the CLI/SDK will attempt to resolve a non-existent endpoint and fail. +## Agentic API Endpoint (Runtime) + +The Agentic API (`transformagenticservice`) is used at runtime for operations like InvokeAgent, SendMessage, ListAgentInstances, and subagent discovery. Like the Registry API, it requires an explicit endpoint. + +**In managed compute** (Bedrock AgentCore, MDE): The `QT_AGENTIC_API_ENDPOINT` environment variable is automatically injected by the platform. + +**For local development**: Set it explicitly: + +```bash +export QT_AGENTIC_API_ENDPOINT=https://iad.prod.agenticapi.elastic-gumby.ai.aws.dev +``` + +| Stage | Region | Endpoint URL | +|-------|--------|-------------| +| prod | us-east-1 | `https://iad.prod.agenticapi.elastic-gumby.ai.aws.dev` | +| prod | eu-central-1 | `https://fra.prod.agenticapi.elastic-gumby.ai.aws.dev` | +| gamma | us-east-1 | `https://iad.gamma.agenticapi.elastic-gumby.ai.aws.dev` | +| gamma | us-west-2 | `https://pdx.gamma.agenticapi.elastic-gumby.ai.aws.dev` | + +The SDK's `get_agentic_api_client()` factory reads this variable. Without it, boto3 attempts to resolve a non-existent public endpoint and fails. + +**NEVER use raw `boto3.client('transformagenticservice')` without setting `endpoint_url`** — use `get_agentic_api_client()` from the SDK which handles this automatically. + ## Registration Flow 1. **Build & containerize** your agent diff --git a/aws-transform-agent-toolkit/steering/getting-started.md b/aws-transform-agent-toolkit/steering/getting-started.md index b33a3bf..75a909b 100644 --- a/aws-transform-agent-toolkit/steering/getting-started.md +++ b/aws-transform-agent-toolkit/steering/getting-started.md @@ -18,6 +18,21 @@ Before starting, ensure you've completed the onboarding steps: **If you haven't done this yet**: The AWS Transform Agent Toolkit onboarding walks you through all installation steps. Kiro will guide you through tool validation, SDK installation, and hook setup when you first activate the power. +## Environment Variables + +These environment variables configure the SDK at runtime: + +| Variable | Required | Description | +|----------|----------|-------------| +| `QT_AGENTIC_API_ENDPOINT` | Yes (local dev) | Agentic API endpoint URL. Auto-injected in managed compute. See [agent-registration.md](./agent-registration.md) for endpoints per stage. | +| `WORKSPACE_ID` | Yes | ATX workspace identifier | +| `JOB_ID` | Yes | Current job identifier | +| `AGENT_INSTANCE_ID` | Yes | Agent instance identifier | +| `AWS_REGION` | Yes | AWS region for Bedrock model inference | +| `ATX_USE_MOCK_REGISTRY` | No | Set to `true` for offline development without platform connectivity | + +For full endpoint details, see the [Agent Registration Guide](./agent-registration.md#agentic-api-endpoint-runtime). + ## What You Can Build With AWS Transform, you create two types of agents: