AWS Reference

Manage, customize, and troubleshoot your AWS deployment.

Manage

Task	Command
Deploy updates	ag infra patch --env prd
Stop deployment	ag infra down --env prd
Force rebuild	ag infra up --env dev -f
Restart local	ag infra up

ag infra down --env prd removes all AWS resources, including the database. Back up your data first.

Customize

Add an agent

Create agents/my_agent.py:

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from db import get_postgres_db

my_agent = Agent(
    id="my-agent",
    name="My Agent",
    model=OpenAIResponses(id="gpt-5.5"),
    db=get_postgres_db(),
    instructions="You are a helpful assistant.",
)

Register in app/main.py:

from agents.my_agent import my_agent

agent_os = AgentOS(
    name="AgentOS",
    agents=[web_search, code_search, my_agent],
)

Restart locally:

ag infra up --env dev

Add tools

Agno includes 100+ tool integrations. See the full list.

from agno.tools.slack import SlackTools
from agno.tools.google_calendar import GoogleCalendarTools

my_agent = Agent(
    tools=[
        SlackTools(),
        GoogleCalendarTools(),
    ],
)

Use a different model

Update your agent:

from agno.models.anthropic import Claude

my_agent = Agent(
    model=Claude(id="claude-sonnet-4-5"),
)

Add the dependency to pyproject.toml and regenerate requirements:

./scripts/generate_requirements.sh
ag infra up --env dev

Add dependencies

1. Edit pyproject.toml
2. Regenerate requirements: ./scripts/generate_requirements.sh
3. Rebuild: ag infra up --env dev

To upgrade all libraries:

./scripts/generate_requirements.sh upgrade

Enable Slack

Add your credentials to infra/secrets/prd_api_secrets.yml:

SLACK_BOT_TOKEN: xoxb-...
SLACK_SIGNING_SECRET: ...

Redeploy to AWS:

ag infra up prd:aws

The interface activates automatically. See Slack setup for creating the Slack app.

Local Development

Run without Docker for faster iteration:

# Set up environment
./scripts/venv_setup.sh
source .venv/bin/activate

# Start PostgreSQL (required)
docker run -d --name agentos-db \
  -e POSTGRES_USER=ai -e POSTGRES_PASSWORD=ai -e POSTGRES_DB=ai \
  -p 5432:5432 pgvector/pgvector:pg17

# Run AgentOS
python -m app.main

Environment Variables

Variable	Required	Default	Description
OPENAI_API_KEY	Yes	—	OpenAI API key
RUNTIME_ENV	No	prd	dev enables hot-reload and disables JWT
JWT_VERIFICATION_KEY	Production	—	Public key from os.agno.com
AGENTOS_URL	No	http://127.0.0.1:8000	Scheduler base URL
SLACK_BOT_TOKEN	No	—	Enable Slack interface
SLACK_SIGNING_SECRET	No	—	Enable Slack interface
PARALLEL_API_KEY	No	—	Parallel SDK key for WebSearch
PORT	No	8000	API server port
DB_HOST	No	localhost	Database host
DB_PORT	No	5432	Database port
DB_USER	No	ai	Database user
DB_PASS	No	ai	Database password
DB_DATABASE	No	ai	Database name

Troubleshooting

AWS credentials error

Reconfigure credentials with aws configure, then validate with aws sts get-caller-identity.

RDS connection timeout

RDS can take about 5 minutes to become available. Check status in AWS Console (RDS → Databases).

ECS task failing

Check CloudWatch logs for container startup errors, missing environment variables, or database connectivity issues.

Load Balancer returns 503

The ECS service may still be starting. Wait 2-3 minutes for target health checks to pass.