Agents¶

Agents are the core building blocks of AG2Trust. Each agent is an AI-powered entity that can process messages, use tools, and collaborate with other agents.

What is an Agent?¶

An agent in AG2Trust is:

• A containerized instance running an LLM-powered assistant
• Configured with a system prompt defining its behavior
• Equipped with tools (capabilities) for specific tasks
• Isolated in its own Docker container for security

Agent Architecture¶

┌─────────────────────────────────────────────────┐
│              Agent Container                     │
│  ┌─────────────────────────────────────────┐   │
│  │         AG2 Framework (AutoGen)          │   │
│  │  ┌─────────────┐  ┌─────────────────┐   │   │
│  │  │ LLM Adapter │  │ Tool Executor   │   │   │
│  │  │ (OpenAI/    │  │ (13 built-in    │   │   │
│  │  │  Anthropic) │  │  tools)         │   │   │
│  │  └─────────────┘  └─────────────────┘   │   │
│  └─────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────┐   │
│  │         Redis Messaging                  │   │
│  │    IN: agent.{id}.in                     │   │
│  │   OUT: agent.{id}.out                    │   │
│  └─────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

Agent Types¶

AG2Trust distinguishes between two agent management patterns:

Standalone Agents (Pets)¶

• Individually managed via the Agents page
• Custom names chosen by users
• Ideal for unique, specialized agents
• Manual scaling

Team Deployment Agents (Cattle)¶

• Auto-scaled via Team Deployments
• System-generated names: {team-slug}-{type-slug}-N
• Managed as a group/pool
• Automatic reconciliation to desired replica count

Creating Agents¶

Required Configuration¶

Optional Configuration¶

Agent Lifecycle¶

States¶

stateDiagram-v2
    [*] --> created
    created --> running: Start
    running --> idle: 30s inactivity
    idle --> running: Message received
    running --> stopped: Stop
    stopped --> running: Start
    running --> error: Failure
    error --> running: Restart
    stopped --> [*]: Delete

Health Monitoring¶

AG2Trust monitors agent health through:

1. Heartbeat: Agents publish heartbeat every 30 seconds (90s TTL)
2. Container Reconciliation: Backend checks Docker every 60 seconds

Agent Communication¶

Receiving Messages¶

Agents receive messages via Redis pub/sub:

Channel: agent.{agent_id}.in

Sending Responses¶

Agents publish responses to:

Channel: agent.{agent_id}.out

Message Format¶

{
  "version": "1.0",
  "timestamp": "2025-01-15T10:30:00Z",
  "trace_id": "abc123",
  "sender": "customer-api",
  "recipient": "agent-1",
  "payload_type": "chat",
  "payload": {
    "message": "Hello, I need help with my order"
  }
}

Agent Tools¶

Agents can use built-in tools based on their assigned capabilities:

File Operations¶

• read_file - Read file contents
• write_file - Write/create files
• list_directory - List directory contents
• delete_file - Remove files
• file_exists - Check file existence

Git Operations¶

• git_status - Check repository status
• git_diff - View changes
• git_commit - Commit changes
• git_push - Push to remote
• git_pull - Pull from remote
• Plus 7 more git tools

Web Operations¶

• http_get - Make GET requests
• http_post - Make POST requests

Search¶

• web_search - Search the internet

Collaboration¶

• discover_agent - Find other agents in team
• send_agent_message - Message another agent

Security¶

Container Isolation¶

Each agent runs in an isolated Docker container with:

• Read-only /app directory
• Write access only to /workspace
• Non-root user execution
• Resource limits (memory, CPU)

Network Isolation¶

┌─────────────────────────────────────┐
│         ag2trust-internal           │
│  (Redis, Postgres - no internet)    │
├─────────────────────────────────────┤
│         ag2trust-public             │
│  (LLM API access only)              │
└─────────────────────────────────────┘

Rate Limiting¶

Best Practices¶

1. Use Descriptive Names¶

# Good
customer-support-tier1
code-review-python
data-analyst-sales

# Avoid
agent1
test
mybot

2. Keep System Prompts Focused¶

# Good: Specific role
You are a Python code reviewer. Review code for:
- Security vulnerabilities
- Performance issues
- Best practice violations

# Avoid: Vague instructions
You are an AI assistant that helps with things.

3. Configure Appropriate Tools¶

Only enable tools the agent needs:

4. Monitor Resource Usage¶

Track in the Dashboard: - Token consumption - Response times - Error rates

API Operations¶

Start Agent¶

POST /api/agents/{id}/start

Stop Agent¶

POST /api/agents/{id}/stop

Send Message¶

POST /api/v1/agents/{id}/messages
Content-Type: application/json

{"message": "Your message here"}

See API Reference for complete documentation.