Agents

Active Development

Agent capabilities and routing features are evolving. Check the changelog for changes to agent configuration.

Agents are AI personas that process webhook events and generate responses. Each agent has a role, system prompt, and optional capabilities that define how it behaves.

Agent Roles

Role	role_id	Default Purpose
PM	pm	Requirements analysis, scope clarification, stakeholder communication
Technical Analyst	ta	Architecture review, feasibility, code quality, estimates
QA	qa	Testing strategy, deployment verification, quality checks
Developer	dev	Code implementation, technical guidance
Hub	hub	System orchestration, workflow coordination

Default Agents

Run POST /api/agents/seed to create the default set of agents:

Agent ID	Name	Role	Specialty
pm_sarah	Sarah (PM)	pm	Requirements, scope, stakeholder sync
ta_leo	Leo (TA)	ta	Architecture, code review, estimates
qa_quinn	Quinn (QA)	qa	Testing, verification, UAT
hub_system	System Hub	hub	Orchestration
dev_alex	Alex (Dev)	dev	Implementation, backend development

Agent Fields

{
  "id": "ta_leo",
  "name": "Leo (Technical Analyst)",
  "role_id": "ta",
  "description": "Technical Analyst specializing in architecture and code review",
  "prompt": "You are Leo...",
  "context": "You have 12 years of backend engineering experience...",
  "identity": "Precise, data-driven, and direct...",
  "responsibilities": [
    "Review technical feasibility of proposed changes",
    "Identify architectural risks and dependencies"
  ],
  "constraints": [
    "Never provide estimates without sufficient context",
    "Never approve changes that violate security best practices"
  ],
  "communication_style": "Technical but accessible..."
}

Field	Required	Description
id	Yes	Unique identifier (snake_case, e.g., ta_leo)
name	Yes	Display name
role_id	Yes	Role: pm, ta, qa, dev, hub
description	No	Short description
prompt	Yes	Core system prompt — defines the agent's behavior
context	No	Background context injected before the prompt
identity	No	Personality and communication style
responsibilities	No	List of what the agent is responsible for
constraints	No	Hard rules — things the agent must never do
communication_style	No	How the agent should communicate

Creating Agents

Via the UI

1. Navigate to Agents in the sidebar
2. Click Create Agent
3. Fill in the required fields (ID, name, role, prompt)
4. Click Save

Via API

curl -X POST http://localhost:8000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ta_leo",
    "name": "Leo (Technical Analyst)",
    "role_id": "ta",
    "description": "Technical Analyst for architecture and code review",
    "prompt": "You are Leo, a Senior Technical Analyst with 12 years of experience in system architecture and code quality. Your role is to review technical aspects of issues and provide actionable guidance.",
    "constraints": [
      "Never approve changes without understanding the full impact",
      "Always flag security concerns explicitly"
    ]
  }'

Via Seeding

# Seed all 5 default agents
curl -X POST http://localhost:8000/api/agents/seed

Returns:

{ "created": 5, "skipped": 0 }

All seed operations are idempotent. Running seed again skips agents that already exist.

Managing Agents

List Agents

curl http://localhost:8000/api/agents

Get a Single Agent

curl http://localhost:8000/api/agents/ta_leo

Update an Agent

curl -X PUT http://localhost:8000/api/agents/ta_leo \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are Leo, an expert architect who prioritizes security and scalability..."
  }'

Delete an Agent

curl -X DELETE http://localhost:8000/api/agents/ta_leo

Agent Capabilities

Capabilities are labels that enable the capability-based routing system to select the best available agent for a task.

Available Capabilities

Common capability labels (you can define any string):

• code_review — Code quality and style review
• security — Security vulnerability analysis
• testing — Test strategy and coverage
• documentation — Technical writing
• api_design — API design and review
• architecture — System design decisions
• performance — Performance analysis and optimization

Adding Capabilities

curl -X POST http://localhost:8000/api/agents/ta_leo/capabilities \
  -H "Content-Type: application/json" \
  -d '{ "capability": "code_review" }'

curl -X POST http://localhost:8000/api/agents/ta_leo/capabilities \
  -H "Content-Type: application/json" \
  -d '{ "capability": "security" }'

Seeding Default Capabilities

curl -X POST http://localhost:8000/api/agents/capabilities/seed

How Capability Routing Works

When a task fires, Aether can select an agent based on capability match score rather than the explicit actor_id in the task. Agents with the best matching capabilities are scored and the highest scorer processes the task. If multiple agents tie, load balancing applies.

This works alongside explicit task-to-agent assignment. Both mechanisms are supported.

Agent Authentication (for External Agents)

If you're building an external agent that connects via the gRPC Agent Gateway, you need to configure authentication on the agent record:

# Enable auth and set a secret
curl -X PUT http://localhost:8000/api/agents/ta_leo \
  -H "Content-Type: application/json" \
  -d '{
    "auth_enabled": true,
    "auth_secret": "your-strong-secret-here"
  }'

The external agent uses this secret when calling RegisterAgent over gRPC. See Agent Runtime Protocol for details.

Trust Levels

Agents that connect via gRPC have a trust level that controls rate limiting:

Level	Description
default	Standard rate limits
trusted	Higher limits — for reliable, vetted agents
privileged	Highest limits — for system-level agents

Set via the agent record or API.

Writing Effective System Prompts

The system prompt is the most important field — it defines how the agent reasons and responds.

PM Agent Example

You are Sarah, an experienced Product Manager with 10 years of experience in B2B SaaS.

Your responsibilities:
- Analyze incoming issues for clarity and completeness
- Extract user stories and acceptance criteria
- Identify ambiguities and ask clarifying questions
- Estimate effort in story points (Fibonacci scale)
- Flag priority conflicts or scope creep

When analyzing an issue, always structure your response as:
1. **Summary**: One-sentence summary of the request
2. **User Story**: As a [user], I want to [goal] so that [benefit]
3. **Acceptance Criteria**: Bullet list of specific, testable criteria
4. **Questions**: Any ambiguities that need clarification
5. **Initial Estimate**: Rough story points (1/2/3/5/8/13)

NEVER:
- Approve issues without acceptance criteria
- Estimate without sufficient context
- Make technical architecture decisions

Technical Analyst Example

You are Leo, a Senior Technical Analyst and Solutions Architect.

Your primary focus is evaluating technical feasibility, identifying risks,
and guiding implementation approaches.

When reviewing an issue:
1. **Feasibility**: Is this technically feasible? What are the risks?
2. **Dependencies**: What systems/services are affected?
3. **Approach**: Recommend the best implementation path
4. **Concerns**: Flag security, performance, or maintainability issues
5. **Estimate**: Rough implementation hours (S/M/L/XL)

NEVER:
- Dismiss concerns without proper analysis
- Approve changes that introduce security vulnerabilities
- Provide estimates for unclear requirements

Audit Log

All agent actions are logged and retrievable:

curl "http://localhost:8000/api/agents/ta_leo/audit?limit=50"

This includes task executions, tool calls, token usage, and timing.

Fallback Behavior

If the agent assigned to a task (actor_id) doesn't exist in the database, Aether uses the task's actor_fallback prompt instead. This ensures tasks always have a way to execute even if an agent is deleted or misconfigured.

Configure fallback prompts when creating tasks:

{
  "actor_id": "ta_leo",
  "actor_fallback": "You are a technical expert. Analyze this issue for technical feasibility and risks."
}