Quickstart (Local Python)

Get a forked Strands Base Agent running locally in under five minutes. This path is best for active development — just run reloads quickly and you have direct access to the venv for debugging.

If you'd rather not install Python 3.14 and uv locally, see the Docker Compose quickstart.

Prerequisites

• Python 3.14
• uv >= 0.9 (matches the version pinned in Dockerfile)
• just command runner
• AWS credentials with Bedrock access (default model provider)
• Access to install foundry-agent-* packages from your team's package registry

Install

1. Clone (or fork) the repository:

   git clone <repo-url>
   cd strands-base-agent

2. Install dependencies and pre-commit hooks:

   just setup

   foundry-agent-* packages are pinned to GitHub Release wheel URLs from boozallen/foundry-agent-packages. A fresh clone resolves all dependencies out of the box. If uv sync or uv lock fails, verify network access to github.com.

3. Configure the environment:

   cp env.template .env
   # Edit .env with your AWS profile or credentials

4. Edit config.yaml with your model and agent settings:

   model:
     provider: bedrock
     model_id: us.anthropic.claude-haiku-4-5-20251001-v1:0
   
   agent_name: my-agent
   system_prompt: >
     You are an AI assistant specialized in your domain.

Run

Start the HTTP server:

just run

Or run a one-shot CLI query:

just demo "Tell me about Python"

Verify

With the server running, hit the health endpoint:

curl http://localhost:8000/api/v1/health

You should receive a JSON response with "status": "healthy". Then test a query:

curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What is machine learning?"}' | jq .

What's Next

• Configuration — full reference for config.yaml and env var overrides
• Adding tools — give your agent domain-specific capabilities
• Customizing the server — wire in custom session managers or model providers