Swap in a real agent Preview

Preview

The worker repository referenced below is still hardening before its OSS release. The Foundry Strands Base Agent — the real agent introduced here — is available today.

This guide picks up where Getting started left off. You already have the Temporal Server, Workflow Worker, and Workflow API running with the mock-strands-agent. Now you'll replace the mock agent with the real Foundry Strands Base Agent — a production-ready, AWS Bedrock–powered A2A agent.

What changes

Component	Before (mock)	After (real)
Agent service	`mock-strands-agent` — canned responses	`strands-base-agent` — live LLM (AWS Bedrock)
Agent port	`8080` (container), `8081` (host)	`8000` (container), `8081` (host)
Health endpoint	`GET /health`	`GET /api/v1/health`
A2A protocol	JSON-RPC 2.0 on `POST /`	JSON-RPC 2.0 via the Strands A2A server
Worker → Agent URL	`http://mock-strands-agent:8080` (Docker DNS)	`http://host.docker.internal:8081` (host network)

The Strands Base Agent runs in its own compose stack on its own network. The worker reaches it via host.docker.internal — the same pattern used to reach the Temporal Server. No shared Docker network is required.

Prerequisites

Everything from Getting started, plus:

AWS credentials configured via AWS SSO or static credentials in ~/.aws:
```
aws sts get-caller-identity
```
The Strands Base Agent uses AWS Bedrock as its default LLM provider. You'll need an AWS account with Bedrock model access enabled in your region (default: us-east-1). Request model access in the AWS Console under Bedrock → Model Access.

Access to the Strands Base Agent repository:

git ls-remote https://github.com/boozallen/strands-base-agent.git

Step 1 — Clone the Strands Base Agent

cd ~/agent-foundry-workspace
git clone https://github.com/boozallen/strands-base-agent.git strands-base-agent

Your workspace should now look like:

agent-foundry-workspace/
├── temporalio/
│   └── docker-compose/                ← Temporal Server
├── temporal-workflow-worker-starter/  ← Worker (preview)
├── temporal-workflow-api-starter/     ← API (preview)
└── strands-base-agent/                ← NEW: real Strands agent (available)

Step 2 — Configure the Strands Base Agent

2.1 Create the environment file

cd ~/agent-foundry-workspace/strands-base-agent
cp env.template .env

2.2 Set the required values

At minimum, verify these settings in .env:

# Server
HOST=0.0.0.0
PORT=8081
LOG_LEVEL=INFO

# AWS — set to your profile name from ~/.aws/config
AWS_PROFILE=<your-aws-profile>
AWS_DEFAULT_REGION=us-east-1

# Model
STRANDS_MODEL_PROVIDER=bedrock
STRANDS_MODEL_ID=us.anthropic.claude-haiku-4-5-20251001-v1:0
STRANDS_TEMPERATURE=0.3
STRANDS_STREAMING=true

# Sessions
STRANDS_SESSION_MANAGER_TYPE=file
STRANDS_SESSION_STORAGE_DIR=./sessions

tip

Set PORT=8081 so the host-mapped port doesn't conflict with the Workflow API on 8000. The agent's compose.yaml maps $PORT:8000, which exposes the agent at localhost:8081.

Check your AWS profiles with aws configure list-profiles. If you only have one, it's likely default.

env.template documents every option, including guardrails, MCP servers, and observability — review it for anything advanced.

2.3 Ensure the sessions directory exists

mkdir -p ~/agent-foundry-workspace/strands-base-agent/sessions/session_default

Step 3 — Stop the mock agent

Free port 8081 before starting the real agent:

cd ~/agent-foundry-workspace/temporal-workflow-worker-starter
docker compose stop mock-strands-agent
docker compose rm -f mock-strands-agent

The worker keeps running.

Step 4 — Start the Strands Base Agent

cd ~/agent-foundry-workspace/strands-base-agent
docker compose up -d

Verify

docker compose ps
sleep 15  # ~15–30s for model initialization
curl http://localhost:8081/api/v1/health
# → {"status":"healthy","timestamp":"...","service_info":{...}}

Step 5 — Update the worker configuration

The worker needs to point to the real agent's external URL. Three files change.

5.1 `config/services.yaml`

cd ~/agent-foundry-workspace/temporal-workflow-worker-starter

Replace the mock agent entry:

# Foundry Strands Base Agent (replaces mock-strands-agent)
strands_agent:
  url: "http://host.docker.internal:8081"
  description: "Foundry Strands Base Agent powered by AWS Bedrock"

host.docker.internal is how a Docker container reaches the host machine — the same pattern used to reach Temporal at host.docker.internal:7233. Port 8081 matches the host-mapped port from the agent's compose stack.

5.2 `src/workflows.py`

In MyWorkflow.run, point the activity at the new services entry:

# Before:
service_config = get_service_config("mock_strands_agent")

# After:
service_config = get_service_config("strands_agent")

5.3 `src/models.py` (optional)

Reflect the real agent in MyWorkflowResult:

# Before:
source: str = "mock-strands-agent"

# After:
source: str = "strands-base-agent"

5.4 `compose.yaml` — remove the mock agent service

services:
  worker:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      - TEMPORAL_HOST=${TEMPORAL_HOST:-temporal:7233}
      - TEMPORAL_NAMESPACE=default
      - TASK_QUEUE=${TASK_QUEUE:-workflow-task-queue}
      - WORKER_IDENTITY=docker-worker-1
      - LOG_LEVEL=INFO
    networks:
      - temporal-network
    restart: unless-stopped
    # NOTE: mock-strands-agent dependency removed — using external strands-base-agent

networks:
  temporal-network:

The mock-strands-agent service and its depends_on block are gone — the real agent runs independently in its own compose stack.

Step 6 — Rebuild and restart the worker

cd ~/agent-foundry-workspace/temporal-workflow-worker-starter
docker compose build worker
docker compose up -d worker
docker compose logs -f worker

Look for:

Loaded workflow: MyWorkflow from src.workflows
Loaded activity: my_activity from src.activities
Temporal worker started successfully

Step 7 — Verify end-to-end with the real agent

7.1 Health-check all three

echo "--- Temporal UI ---"
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8080

echo "--- Workflow API ---"
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8000/health/

echo "--- Strands Base Agent ---"
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8081/api/v1/health

All three should return HTTP 200.

7.2 Start a test workflow

curl -X POST http://localhost:8000/workflows/start \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_type": "MyWorkflow",
    "workflow_id": "test-real-agent-001",
    "args": [{"user_name": "Developer", "task_type": "greeting", "language": "en"}]
  }'

7.3 Monitor in the Temporal UI

Open http://localhost:8080.
Select the default namespace.
Find workflow test-real-agent-001. Step 2 should now show a real LLM-generated response instead of the canned mock.

7.4 Check the agent logs

cd ~/agent-foundry-workspace/strands-base-agent
docker compose logs -f

You should see incoming A2A JSON-RPC requests being processed.

Updated architecture

┌─────────────────────┐       ┌──────────────────────────┐
│   Workflow API       │       │   Temporal Server         │
│   (FastAPI)          │──────▶│   (PostgreSQL-backed)     │
│   localhost:8000     │       │   gRPC: localhost:7233    │
└─────────────────────┘       │   UI:   localhost:8080    │
                               └──────────┬───────────────┘
                                          │
                               ┌──────────▼───────────────┐
                               │   Workflow Worker         │
                               │   (temporal-network)      │
                               │   Polls task queue        │
                               └──────────┬───────────────┘
                                          │ host.docker.internal:8081
                               ┌──────────▼───────────────┐
                               │   Strands Base Agent      │
                               │   (AWS Bedrock LLM)       │
                               │   localhost:8081          │
                               │   A2A JSON-RPC 2.0       │
                               └──────────────────────────┘

Updated service reference

Item	Value
Repository	`strands-base-agent/`
Compose file	`strands-base-agent/compose.yaml`
Environment file	`strands-base-agent/.env`
Health endpoint	`http://localhost:8081/api/v1/health`
A2A endpoint	`http://localhost:8081/` (JSON-RPC 2.0)
Query endpoint	`http://localhost:8081/api/v1/query`
Worker → Agent URL	`http://host.docker.internal:8081`

Common operations

Restart everything (with the real agent)

# 1. Temporal Server
cd ~/agent-foundry-workspace/temporalio/docker-compose
docker compose -f docker-compose-postgres.yml up -d
sleep 30

# 2. Strands Base Agent
cd ~/agent-foundry-workspace/strands-base-agent && docker compose up -d

# 3. Worker
cd ~/agent-foundry-workspace/temporal-workflow-worker-starter && docker compose up -d

# 4. API
cd ~/agent-foundry-workspace/temporal-workflow-api-starter && docker compose up -d

Switch back to the mock agent

Stop the real agent: cd ~/agent-foundry-workspace/strands-base-agent && docker compose down.
Revert config/services.yaml to the mock_strands_agent entry.
Revert src/workflows.py to get_service_config("mock_strands_agent").
Restore the mock-strands-agent service in the worker's compose.yaml and rebuild.

Troubleshooting

AWS credentials not found

botocore.exceptions.NoCredentialsError: Unable to locate credentials

Ensure ~/.aws contains valid credentials or SSO configuration.
Verify AWS_PROFILE in .env matches a profile from aws configure list-profiles.
For SSO: aws sso login --profile <your-profile>.

Bedrock model access denied

AccessDeniedException: You don't have access to the model

Enable Bedrock model access in the AWS Console for your region.
Check the model ID in .env (STRANDS_MODEL_ID) is available in your account.

Agent container fails to start

cd ~/agent-foundry-workspace/strands-base-agent
docker compose logs strands-agent

Common causes:

Missing sessions/session_default directory — mkdir -p sessions/session_default.
Missing or misconfigured ~/.aws.

Worker can't reach the agent

ConnectionError: Cannot connect to host.docker.internal:8081

Agent is healthy: curl http://localhost:8081/api/v1/health.

host.docker.internal resolves from inside the worker:

docker compose exec worker curl http://host.docker.internal:8081/api/v1/health

config/services.yaml uses host.docker.internal:8081, not localhost (inside a container, localhost is the container itself).

Slow responses or timeouts

The real agent calls Bedrock, which is slower than the mock. Defaults:

start_to_close_timeout = 5 minutes (sufficient for most calls).
heartbeat_timeout = 30 seconds — the call_strands_agent activity sends periodic heartbeats automatically.

If you still see timeouts, increase the per-activity timeout in src/workflows.py or check Bedrock service health.

What's next

Ready to build multi-phase workflows with human-in-the-loop feedback loops? Continue with Loops & advanced workflows.

What changes​

Prerequisites​

Step 1 — Clone the Strands Base Agent​

Step 2 — Configure the Strands Base Agent​

2.1 Create the environment file​

2.2 Set the required values​

2.3 Ensure the sessions directory exists​

Step 3 — Stop the mock agent​

Step 4 — Start the Strands Base Agent​

Verify​

Step 5 — Update the worker configuration​

5.1 config/services.yaml​

5.2 src/workflows.py​

5.3 src/models.py (optional)​

5.4 compose.yaml — remove the mock agent service​

Step 6 — Rebuild and restart the worker​

Step 7 — Verify end-to-end with the real agent​

7.1 Health-check all three​

7.2 Start a test workflow​

7.3 Monitor in the Temporal UI​

7.4 Check the agent logs​

Updated architecture​

Updated service reference​

Common operations​

Restart everything (with the real agent)​

Switch back to the mock agent​

Troubleshooting​

AWS credentials not found​

Bedrock model access denied​

Agent container fails to start​

Worker can't reach the agent​

Slow responses or timeouts​

What's next​