Agents

type AgentInstance struct {
    ID             string                    // Unique identifier (e.g., "main", "worker")
    Name           string                    // Display name
    Model          string                    // Primary LLM model
    Fallbacks      []string                  // Fallback model list
    Workspace      string                    // Workspace directory path
    MaxIterations  int                       // Max tool use loops per request
    MaxTokens      int                       // Context window size
    Temperature    float64                   // LLM sampling temperature (0.0-1.0)
    Provider       providers.LLMProvider     // LLM provider instance
    Sessions       *session.SessionManager   // Conversation history manager
    ContextBuilder *ContextBuilder           // System prompt builder
    Tools          *tools.ToolRegistry       // Available tools
    Subagents      *config.SubagentsConfig   // Subagent spawn permissions
    SkillsFilter   []string                  // Enabled skills (nil = all)
    Candidates     []providers.FallbackCandidate // Resolved fallback chain
}

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model": "gpt4",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20,
      "restrict_to_workspace": true
    }
  }
}

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model": "gpt4"
    },
    "agents": [
      {
        "id": "main",
        "name": "Main Assistant",
        "default": true,
        "model": {
          "primary": "gpt4",
          "fallbacks": ["claude-sonnet-4.6", "glm-4.7"]
        }
      },
      {
        "id": "researcher",
        "name": "Research Assistant",
        "model": {
          "primary": "claude-sonnet-4.6"
        },
        "skills": ["research", "web-search"]
      },
      {
        "id": "coder",
        "name": "Code Assistant",
        "workspace": "~/.picoclaw/workspace-coder",
        "model": {
          "primary": "gpt4"
        },
        "skills": ["coding", "git"]
      }
    ]
  }
}

~/.picoclaw/workspace/          # Default agent
├── sessions/                   # Conversation sessions
│   ├── main.json              # Default session
│   ├── telegram-123456.json   # Per-channel sessions
│   └── agent:worker.json      # Cross-agent sessions
├── memory/
│   └── MEMORY.md              # Long-term memory
├── state/
│   └── state.json             # Persistent state (last channel, etc.)
├── cron/
│   └── jobs.json              # Scheduled tasks
├── skills/                    # Installed skills
│   └── research/
├── AGENTS.md                  # Agent behavior guide
├── SOUL.md                    # Agent personality
├── IDENTITY.md                # Agent identity
├── USER.md                    # User preferences
├── TOOLS.md                   # Tool usage guidelines
└── HEARTBEAT.md               # Periodic tasks

# Periodic Tasks

## Quick Tasks (respond directly)
- Report current time

## Long Tasks (use spawn for async)
- Search the web for AI news and summarize
- Check email and report important messages

type SessionManager struct {
    sessionsDir string
}

// Core methods
func (sm *SessionManager) GetHistory(sessionKey string) []providers.Message
func (sm *SessionManager) AddMessage(sessionKey, role, content string)
func (sm *SessionManager) SetSummary(sessionKey, summary string)
func (sm *SessionManager) Save(sessionKey string)

AGENTS.md content

SOUL.md content

IDENTIY.md content

USER.md content

Loaded skills:
- skill-name: description

Available tools:
- tool_name: description

[
  {"role": "user", "content": "What is 2+2?"},
  {"role": "assistant", "content": "4"},
  {"role": "user", "content": "What is 5+5?"}
]

for iteration < MaxIterations {
    // 1. Call LLM with current messages + tools
    response, err := provider.Chat(ctx, messages, tools, model, options)
    
    // 2. If no tool calls, return final response
    if len(response.ToolCalls) == 0 {
        return response.Content
    }
    
    // 3. Execute all tool calls
    for _, toolCall := range response.ToolCalls {
        result := tools.Execute(ctx, toolCall.Name, toolCall.Arguments)
        messages = append(messages, toolResultMessage)
    }
    
    // 4. Continue to next iteration
    iteration++
}

"I've completed processing but have no response to give. Increase `max_tool_iterations` in config.json."

{
  "task": "Search for AI news and summarize",
  "label": "AI News Research",
  "agent_id": "researcher"
}

{
  "agents": {
    "agents": [
      {
        "id": "main",
        "subagents": {
          "allowlist": ["researcher", "coder"]
        }
      },
      {
        "id": "researcher",
        "subagents": {
          "allowlist": []  // Cannot spawn subagents
        }
      }
    ]
  }
}

{
  "agents": {
    "routing": {
      "rules": [
        {
          "channel": "discord",
          "guild_id": "123456789",
          "agent_id": "coder"
        },
        {
          "channel": "telegram",
          "peer": {"kind": "group", "id": "987654321"},
          "agent_id": "researcher"
        }
      ]
    }
  }
}

~/.picoclaw/workspace/          # Main agent
~/.picoclaw/workspace-researcher/  # Researcher agent
~/.picoclaw/workspace-coder/    # Coder agent

{
  "model": {
    "primary": "gpt4",
    "fallbacks": ["claude-sonnet-4.6", "glm-4.7", "gemini-2.0"]
  }
}