Agents

Agents are AI personalities that can think, communicate, and collaborate. Each agent has unique traits, skills, and behaviors.

Agent Anatomy

An agent consists of:

┌─────────────────────────────────────────┐
│                 Agent                    │
├─────────────────────────────────────────┤
│  Identity                               │
│  ├── Name, Role, Background             │
│  └── Model & Provider                   │
├─────────────────────────────────────────┤
│  Personality                            │
│  ├── Traits (curious, analytical, etc.) │
│  └── Communication style                │
├─────────────────────────────────────────┤
│  Capabilities                           │
│  ├── Skills & Competencies              │
│  └── Tools (filesystem, calculator)     │
├─────────────────────────────────────────┤
│  Memory                                 │
│  ├── Short-term (conversation)          │
│  └── Long-term (persistent)             │
└─────────────────────────────────────────┘

Creating Agents

Basic Agent

curl -X POST http://localhost:8000/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sophie",
    "role": "Software Architect",
    "provider": "openai",
    "model": "gpt-4"
  }'

Full Agent Configuration

curl -X POST http://localhost:8000/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sophie Chen",
    "role": "Lead Technical Architect",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "personality": {
      "traits": ["analytical", "creative", "detail-oriented"],
      "communication_style": "professional",
      "languages": ["English", "French", "Mandarin"]
    },
    "background": {
      "history": "15 years in software architecture, PhD from MIT",
      "expertise": ["distributed systems", "API design", "cloud architecture"]
    },
    "config": {
      "temperature": 0.7,
      "max_tokens": 4096
    }
  }'

Supported Providers

GatheRing supports multiple LLM providers:

OpenAI

{
  "provider": "openai",
  "model": "gpt-4o"
}

Available models: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo

Anthropic

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514"
}

Available models: claude-sonnet-4-20250514, claude-opus-4-20250514, claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022

Ollama (Local)

{
  "provider": "ollama",
  "model": "llama3.2"
}

Available models: Any model installed in your local Ollama instance

Choosing the Right Provider

Provider	Use Case	Considerations
OpenAI	General purpose, wide compatibility	API costs, rate limits
Anthropic	Long context, complex reasoning	API costs, rate limits
Ollama	Privacy, offline use, cost control	Requires local setup, hardware dependent

Personality System

Available Traits

Category	Traits
Cognitive	`analytical`, `creative`, `logical`, `intuitive`
Social	`empathetic`, `collaborative`, `diplomatic`, `direct`
Work Style	`detail-oriented`, `big-picture`, `methodical`, `agile`
Communication	`formal`, `casual`, `technical`, `accessible`

Trait Intensity

Traits can have varying intensities (0.0 to 1.0):

{
  "personality": {
    "traits": {
      "curious": 0.9,
      "analytical": 0.8,
      "creative": 0.6
    }
  }
}

Communication Styles

professional: Formal, structured responses
casual: Friendly, conversational tone
technical: Precise, jargon-appropriate
accessible: Simple, clear explanations

Agent Skills

Built-in Skills

{
  "skills": [
    "code_review",
    "documentation",
    "testing",
    "debugging",
    "architecture"
  ]
}

Custom Competencies

{
  "competencies": {
    "python": "expert",
    "react": "advanced",
    "kubernetes": "intermediate",
    "machine_learning": "basic"
  }
}

Agent Tools

Agents can use tools to interact with the world:

Available Tools

Tool	Description
`filesystem`	Read/write files
`calculator`	Mathematical operations
`web_search`	Search the web
`code_executor`	Run code snippets
`git`	Git operations

Configuring Tools

{
  "tools": {
    "filesystem": {
      "enabled": true,
      "permissions": ["read", "write"],
      "base_path": "/workspace"
    },
    "calculator": {
      "enabled": true
    }
  }
}

Agent Memory

Memory Scopes

Conversation: Current conversation context
Session: Current session across conversations
Agent: Persistent agent-specific memories
Circle: Shared with circle members
Global: Shared across all agents

Memory Operations

# Get agent memories
curl http://localhost:8000/agents/1/memories

# Add a memory
curl -X POST http://localhost:8000/agents/1/memories \
  -H "Content-Type: application/json" \
  -d '{
    "key": "user_preference",
    "value": "Prefers detailed explanations",
    "scope": "agent"
  }'

Agent States

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Idle    │────▶│  Active  │────▶│  Busy    │
└──────────┘     └──────────┘     └──────────┘
     ▲                                  │
     └──────────────────────────────────┘

States

Idle: Ready to receive tasks
Active: Engaged in conversation
Busy: Processing a complex task
Offline: Not available

Agent Sessions

Sessions track agent activity:

# Start a session
curl -X POST http://localhost:8000/agents/1/sessions

# Get current session
curl http://localhost:8000/agents/1/sessions/current

# End session
curl -X POST http://localhost:8000/agents/1/sessions/current/end

Using Personas

GatheRing includes pre-built personas for common roles. See the personas/ directory for examples:

sophie_chen.md - Lead Technical Architect
olivia_nakamoto.md - Senior Systems Engineer
marcus_johnson.md - DevOps Engineer
And many more…

Loading a Persona

from gathering import Agent

# Load from persona file
agent = Agent.from_persona("personas/sophie_chen.md")

Best Practices

1. Match Model to Task

Use faster/cheaper models for simple tasks, more capable models for complex reasoning.

2. Define Clear Roles

Each agent should have a specific, well-defined role.

3. Balanced Personalities

Avoid extreme trait intensities; balance creates more natural interactions.

4. Appropriate Memory Scope

Use the narrowest scope that works for your use case.

5. Tool Permissions

Only grant tools that the agent actually needs.