Agents

An agent in SwiftClaw is an autonomous AI program that can perceive its environment, make decisions, and take actions to achieve specific goals.

What is an Agent?

An agent consists of:

Model: The AI model powering the agent (GPT-4, Claude, etc.)
Memory: Short-term and long-term context storage
Tools: Functions the agent can call to interact with external systems
Triggers: Events that activate the agent (API calls, webhooks, schedules)
Configuration: Parameters controlling agent behavior

Autonomous Execution: Agents run independently, making decisions based on their configuration and learned context.

Agent Lifecycle

1. Creation

Create an agent via dashboard or CLI:

swiftclaw agents create customer-support \
  --model gpt-4 \
  --memory persistent \
  --workspace ~/.swiftclaw/customer-support

2. Configuration

Configure agent behavior:

{
  "name": "customer-support",
  "model": {
    "primary": "gpt-4",
    "fallbacks": ["claude-3-sonnet"],
    "temperature": 0.7,
    "maxTokens": 2000
  },
  "memory": {
    "type": "persistent",
    "scope": "per-user",
    "ttl": "30d"
  },
  "tools": [
    "search_knowledge_base",
    "create_ticket",
    "send_email"
  ]
}

3. Deployment

Deploy to production:

swiftclaw deploy customer-support

SwiftClaw handles:

Infrastructure provisioning
Dependency installation
Environment configuration
Health checks
Load balancing

4. Execution

Agent processes requests:

Receives trigger (API call, webhook, schedule)
Loads relevant memory and context
Processes input with AI model
Executes tools if needed
Updates memory
Returns response

5. Monitoring

Track agent performance:

swiftclaw agents status customer-support
swiftclaw logs customer-support --follow

Agent Types

Conversational Agents

Handle natural language interactions:

from swiftclaw import Agent

agent = Agent(
    name="chatbot",
    model="gpt-4",
    system_prompt="You are a helpful customer support assistant."
)

@agent.on_message
async def handle_chat(message):
    return await agent.generate(
        prompt=message.content,
        context=message.session.history
    )

Task Agents

Execute specific tasks:

agent = Agent(
    name="data-processor",
    model="gpt-4",
    tools=["fetch_data", "transform_data", "store_results"]
)

@agent.on_schedule("0 */6 * * *")  # Every 6 hours
async def process_data():
    data = await agent.call_tool("fetch_data")
    transformed = await agent.call_tool("transform_data", data)
    await agent.call_tool("store_results", transformed)

Multi-Agent Systems

Coordinate multiple agents:

# Coordinator agent
coordinator = Agent(
    name="coordinator",
    model="gpt-4",
    agents=["researcher", "writer", "reviewer"]
)

@coordinator.on_message
async def coordinate(message):
    # Research phase
    research = await coordinator.delegate("researcher", message)
    
    # Writing phase
    draft = await coordinator.delegate("writer", research)
    
    # Review phase
    final = await coordinator.delegate("reviewer", draft)
    
    return final

Agent Configuration

Model Selection

Choose the right model for your use case:

{
  "model": {
    "primary": "gpt-4",           // Main model
    "fallbacks": [                // Fallback models
      "claude-3-sonnet",
      "gemini-pro"
    ],
    "routing": {                  // Smart routing
      "simple": "llama-3",        // Use cheaper model for simple tasks
      "complex": "gpt-4"          // Use powerful model for complex tasks
    }
  }
}

Memory Configuration

Control how agents remember:

{
  "memory": {
    "type": "persistent",         // persistent | ephemeral
    "scope": "per-user",          // per-user | per-session | global
    "ttl": "30d",                 // Time to live
    "maxSize": "100MB",           // Maximum memory size
    "search": {
      "enabled": true,
      "type": "hybrid",           // hybrid | vector | text
      "vectorWeight": 0.7,
      "textWeight": 0.3
    }
  }
}

Tool Configuration

Define available tools:

{
  "tools": [
    {
      "name": "search_knowledge_base",
      "description": "Search the knowledge base for information",
      "parameters": {
        "query": "string",
        "limit": "number"
      }
    },
    {
      "name": "create_ticket",
      "description": "Create a support ticket",
      "parameters": {
        "title": "string",
        "description": "string",
        "priority": "string"
      }
    }
  ]
}

Agent Isolation

Each agent runs in isolation:

Dedicated Resources: Separate compute and memory
Independent Workspaces: Isolated file systems
Separate Memory: No cross-agent memory access
Individual Scaling: Scale agents independently

Security: Agents cannot access each other's data unless explicitly configured for multi-agent communication.

Agent Bindings

Bind agents to specific channels:

# Bind to WhatsApp
swiftclaw agents bind customer-support whatsapp:personal

# Bind to Slack
swiftclaw agents bind customer-support slack:work

# Bind to Discord
swiftclaw agents bind customer-support discord:community

Multiple agents can be bound to the same channel with routing rules:

{
  "routing": {
    "whatsapp:personal": {
      "default": "customer-support",
      "rules": [
        {
          "pattern": "billing|payment|invoice",
          "agent": "billing-agent"
        },
        {
          "pattern": "technical|bug|error",
          "agent": "technical-support"
        }
      ]
    }
  }
}

Agent Persistence

Configure how agent state persists:

Execution-Scoped

Memory dies with the execution:

{
  "persist": true,
  "scope": "execution"
}

Project-Scoped

Memory survives across executions:

{
  "persist": "project",
  "path": ".swiftclaw/agents/my-agent"
}

Custom Path

Shared memory across projects:

{
  "persist": "~/.swiftclaw/shared/my-agent"
}

Best Practices

1. Use Appropriate Models

Don't use GPT-4 for simple tasks:

# Good: Use cheaper models for classification
classifier = Agent(model="llama-3")

# Good: Use powerful models for complex reasoning
analyst = Agent(model="gpt-4")

2. Implement Proper Memory Management

Set appropriate TTLs:

{
  "memory": {
    "shortTerm": { "ttl": "1h" },    // Session data
    "longTerm": { "ttl": "30d" }     // User preferences
  }
}

3. Use Tool Calling Effectively

Provide clear tool descriptions:

@agent.tool
async def search_docs(query: str, limit: int = 5):
    """
    Search documentation for relevant information.
    
    Args:
        query: Search query string
        limit: Maximum number of results (default: 5)
    
    Returns:
        List of relevant documentation snippets
    """
    # Implementation

4. Monitor Agent Performance

Set up alerts:

swiftclaw alerts create \
  --agent customer-support \
  --metric response-time \
  --threshold 2s \
  --action notify

5. Version Your Agents

Use version control:

# Tag releases
git tag v1.0.0
git push origin v1.0.0

# Deploy specific version
swiftclaw deploy customer-support --version v1.0.0

Next Steps

Models - Learn about AI model selection
Memory - Understand memory patterns
Channels - Deploy to messaging platforms
Monitoring - Track agent performance