Circles

Circles are the core organizational unit in GatheRing. They represent groups of AI agents that collaborate on a common theme, project, or domain.

What is a Circle?

A Circle is:

A container for related agents
A context for conversations
A scope for shared memory and knowledge
A boundary for permissions and access

Think of a circle as a team room where agents meet to discuss and work together.

Circle Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Created   │────▶│   Active    │────▶│   Archived  │
└─────────────┘     └─────────────┘     └─────────────┘
                          │
                          ▼
                    ┌─────────────┐
                    │   Paused    │
                    └─────────────┘

States

Created: Circle exists but hasn’t started
Active: Circle is running, agents can converse
Paused: Temporarily stopped, can be resumed
Archived: Permanently stopped, read-only

Creating Circles

Via API

curl -X POST http://localhost:8000/circles \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-team",
    "display_name": "Development Team",
    "description": "Frontend and backend developers",
    "config": {
      "max_agents": 10,
      "conversation_mode": "round_robin"
    }
  }'

Via Python

from gathering import Circle

circle = Circle(
    name="dev-team",
    display_name="Development Team",
    description="Frontend and backend developers",
    config={
        "max_agents": 10,
        "conversation_mode": "round_robin"
    }
)
await circle.save()

Managing Agents in Circles

Adding Agents

# Add an agent to a circle
curl -X POST http://localhost:8000/circles/dev-team/agents \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 1}'

Removing Agents

curl -X DELETE http://localhost:8000/circles/dev-team/agents/1

Listing Circle Agents

curl http://localhost:8000/circles/dev-team/agents

Circle Configuration

Conversation Modes

Mode	Description
`round_robin`	Agents take turns in order
`reactive`	Agents respond when relevant
`moderated`	A lead agent directs conversation
`free_form`	Any agent can speak anytime

Example Configuration

{
  "name": "research-team",
  "config": {
    "max_agents": 5,
    "conversation_mode": "moderated",
    "moderator_agent_id": 1,
    "turn_timeout": 30,
    "max_turns_per_conversation": 50,
    "memory_scope": "circle",
    "allow_tools": true
  }
}

Circle Operations

Start a Circle

curl -X POST http://localhost:8000/circles/dev-team/start

Pause a Circle

curl -X POST http://localhost:8000/circles/dev-team/pause

Resume a Circle

curl -X POST http://localhost:8000/circles/dev-team/resume

Archive a Circle

curl -X POST http://localhost:8000/circles/dev-team/archive

Conversations in Circles

Conversations happen within circles:

curl -X POST http://localhost:8000/conversations \
  -H "Content-Type: application/json" \
  -d '{
    "circle_name": "dev-team",
    "topic": "API Design Review",
    "agent_ids": [1, 2, 3],
    "initial_prompt": "Let'\''s review the new REST API design"
  }'

Advancing Conversations

curl -X POST http://localhost:8000/conversations/1/advance \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What about error handling?"}'

Circle Memory

Each circle has its own memory scope:

Circle-scoped memories: Shared by all agents in the circle
Agent-scoped memories: Private to each agent
Conversation memories: Specific to each conversation

Accessing Circle Memory

# Get circle knowledge
curl http://localhost:8000/circles/dev-team/knowledge

# Add knowledge to circle
curl -X POST http://localhost:8000/circles/dev-team/knowledge \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Standards",
    "content": "All APIs must follow REST conventions...",
    "category": "best_practice"
  }'

Best Practices

1. Name Circles Meaningfully

Use descriptive names that reflect the circle’s purpose:

dev-team - Development team
security-review - Security reviewers
customer-support - Support agents

2. Limit Circle Size

Keep circles focused with 3-7 agents for best results.

3. Define Clear Roles

Each agent in a circle should have a distinct role:

circle.add_agent(architect, role="lead")
circle.add_agent(developer, role="implementer")
circle.add_agent(reviewer, role="quality")

4. Use Appropriate Conversation Modes

Brainstorming: Use free_form
Technical review: Use moderated
Pair work: Use round_robin