Agents

Agents are the core unit of organization in Uranus. Each agent is an isolated AI-powered entity with its own configuration, state, and capabilities.

Overview

An agent represents:

• A distinct AI persona with specific capabilities
• Isolated state and configuration
• Dedicated Durable Object instance
• Scoped access to workflows, schedules, and data

Creating an Agent

Via Dashboard

1. Navigate to the main dashboard
2. Click Create Agent
3. Fill in the details:
   • Name - Unique identifier
   • Description - Purpose of the agent
4. Configure initial settings

Via API

curl -X POST https://your-domain.com/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot",
    "description": "Customer support automation agent"
  }'

Agent Configuration

LLM Settings

Configure the AI model powering your agent:

Setting	Description	Default
llm_provider	AI provider (workers-ai, openai, anthropic)	workers-ai
llm_model	Model name	@cf/meta/llama-3.1-8b-instruct
llm_temperature	Response creativity (0-1)	0.7
llm_max_tokens	Maximum response length	2048
llm_system_prompt	Agent behavior instructions	(default prompt)

Calendar Settings

Setting	Description	Default
calendar_timezone	Agent timezone	UTC
calendar_working_hours_start	Working hours start	09:00
calendar_working_hours_end	Working hours end	17:00
calendar_default_duration	Default task duration (minutes)	30

Workflow Settings

Setting	Description	Default
workflow_max_concurrent	Max parallel workflows	5
workflow_default_timeout	Timeout in seconds	300
workflow_retry_attempts	Retry count on failure	3
workflow_retry_delay	Delay between retries (seconds)	60

Browser Settings

Setting	Description	Default
browser_headless	Run without UI	true
browser_viewport_width	Browser width	1280
browser_viewport_height	Browser height	720
browser_user_agent	Custom user agent	(browser default)
browser_default_timeout	Action timeout (ms)	30000

Agent State

Each agent maintains persistent state:

interface AgentState {
  config: {
    name: string
    description: string
    model: string
    temperature: number
  }
  connectedClients: number
  mcpServers: MCPServer[]
  pendingSchedules: Schedule[]
}

Viewing State

Access the State page in the dashboard to:

• View current configuration
• Monitor connected clients
• See active MCP servers
• Review pending schedules

Updating State

State updates are synchronized across all connected clients via WebSocket.

Access Control

Roles

Role	Permissions
Owner	Full access, can delete agent
Admin	Full access, cannot delete
Viewer	Read-only access

Managing Access

# Add an admin
curl -X POST https://your-domain.com/api/agents/{id}/admins \
  -d '{"email": "user@example.com", "role": "admin"}'

Default Agent

A special default agent is always available:

• Accessible without authentication
• Used for initial setup
• Cannot be deleted

Agent Isolation

Each agent is fully isolated:

┌─────────────────────────────────────────────┐
│                System                        │
├──────────────┬──────────────┬───────────────┤
│   Agent A    │   Agent B    │   Agent C     │
│              │              │               │
│  Workflows   │  Workflows   │  Workflows    │
│  Schedules   │  Schedules   │  Schedules    │
│  Contacts    │  Contacts    │  Contacts     │
│  Chat        │  Chat        │  Chat         │
│  Browser     │  Browser     │  Browser      │
│  Sources     │  Sources     │  Sources      │
│              │              │               │
│  ═══════════ │ ═══════════  │ ═══════════   │
│  Durable Obj │ Durable Obj  │ Durable Obj   │
└──────────────┴──────────────┴───────────────┘

Multi-Agent Communication

Agents can communicate via Agent Connections:

// Create connection between agents
const connection = {
  source_agent_id: 'agent-a',
  target_agent_id: 'agent-b',
  connection_type: 'webhook',
  config: {
    url: 'https://...',
    events: ['workflow.complete', 'message.received']
  }
}

Best Practices

1. Single Responsibility

Create focused agents for specific tasks:

• support-bot - Customer support
• data-processor - ETL workflows
• social-manager - Social media automation

2. Environment Separation

Use different agents for:

• Development/testing
• Staging
• Production

3. System Prompts

Write clear, specific system prompts:

You are a customer support agent for Acme Corp.
Your responsibilities:
- Answer product questions
- Help with order issues
- Escalate complex cases to humans

Always be polite and professional.
Never make promises you can't keep.

4. Resource Limits

Configure appropriate limits:

• Set realistic workflow_max_concurrent
• Use reasonable browser_default_timeout
• Monitor quota usage

API Reference

See Agents API for complete endpoint documentation.