Agents & Workflows

Zubo supports custom sub-agents, multi-agent delegation, structured workflows, and agent teams. This allows you to create specialized agents for specific tasks and orchestrate them together into powerful, composable pipelines that go far beyond what a single agent can accomplish on its own.

Copy-Paste Task Cards

zubo config set auth.enabled true
zubo auth create-key my-app

zubo config set failover '["openai","ollama"]'
zubo config set providers.ollama.model llama3.3

Common Errors

curl -H "Authorization: Bearer YOUR_KEY" http://localhost:3000/api/dashboard/status

zubo model openai/gpt-4o-mini
zubo logs --follow

ollama serve
ollama pull llama3.3

The Default Agent

By default, Zubo operates as a single agent that handles all messages across every connected channel using a unified session identified as "owner." This default agent has access to all registered tools — both built-in tools and any user-installed skills — and its personality and behavior are defined by the system prompt stored at ~/.zubo/workspace/SYSTEM.md.

For many use cases, the default agent is all you need. It can search the web, manage your calendar, write code, read and write memory, and use any skill you install. Custom agents become valuable when you want to restrict tool access, provide specialized instructions, or build multi-step workflows.

Personality

The system prompt defines your agent's personality, rules, and background knowledge. There are two ways to customize it:

• Edit the file directly — Open ~/.zubo/workspace/SYSTEM.md in any text editor and modify it.
• Use the dashboard — Navigate to the Personality panel in the web dashboard and edit it there. Changes are saved to SYSTEM.md automatically.

Replace mode: By default, SYSTEM.md is appended to Zubo's built-in system prompt. If you want your file to fully replace defaults, add the marker zubo:replace-default anywhere in SYSTEM.md.

Here is an example SYSTEM.md that defines a personalized assistant:

# System Prompt

You are Zubo, a personal AI assistant for Thomas.

## Personality
- Friendly but concise. Avoid unnecessary filler.
- Use a professional tone for work topics, casual for personal.
- When unsure, ask clarifying questions rather than guessing.

## Rules
- Always check memory before answering personal questions.
- Never share API keys, passwords, or sensitive data in chat.
- Prefer short answers unless the user asks for detail.

## Context
- Thomas is a software engineer working on a Rust project called "relay."
- His timezone is America/New_York.
- He prefers metric units and Markdown formatting.

The system prompt is loaded fresh on every message, so changes take effect immediately without restarting Zubo.

Self-Configuration

Zubo can modify its own configuration at runtime through the built-in config_update tool. You do not need to edit config.json by hand — just tell Zubo what you want to change in plain language and it will update the configuration file for you.

What Zubo Can Change

• Switch LLM providers — "Use GPT-4o" updates activeProvider to openai.
• Set budgets — "Limit my daily spending to $5" updates budget.dailyLimitUsd.
• Enable smart routing — "Enable smart routing with Groq" updates smartRouting.enabled and smartRouting.fastProvider.
• Change its name — "Call yourself Jarvis" updates agentName.
• Toggle features — Enable or disable channels, change the heartbeat interval, adjust max turns, and more.

What It Cannot Change

• API keys and tokens — For security, secrets are never stored through config_update. Zubo uses the separate secret_set tool to securely store API keys, passwords, and tokens.
• Channel restarts — Channel configuration changes (enabling Telegram, changing a bot token) require a restart to take effect.

Example

You: I want to switch to Claude Opus for complex tasks but use Groq for simple ones

Zubo: Done! I've set your active provider to Anthropic and enabled smart
routing with Groq as the fast provider. Simple queries like greetings
will use Groq (fast, inexpensive), while complex tasks like code
generation and multi-step reasoning use Claude.

# Under the hood, Zubo called config_update three times:
#   set activeProvider = "anthropic"
#   set smartRouting.enabled = true
#   set smartRouting.fastProvider = "groq"

How Zubo Learns

Zubo's memory is organized into three complementary layers, each serving a different purpose. Together, they give the agent persistent, searchable, and structured knowledge that improves over time.

1. Conversational Memory

Every conversation session is automatically persisted. Recent messages are always included in the LLM context, so Zubo remembers what you discussed earlier in the same session without any explicit action on your part.

2. Semantic Memory

Facts, notes, and documents saved via the memory_write tool are chunked, embedded as 384-dimensional vectors, and indexed for full-text search. When you send a message, Zubo automatically runs a hybrid search (60% vector similarity + 40% keyword matching) to find relevant memories and inject them into the context. See the Memory System page for full details.

3. Knowledge Graph

Structured entity-relationship memory captures discrete facts in a queryable format. Entities (people, projects, organizations, concepts) are linked by labeled relationships (works_on, manages, uses). When you mention a known entity, its graph context is automatically injected into the LLM prompt.

How the Layers Work Together

You: I'm working with Alex on the Horizon project. He handles backend,
     I do frontend.

Zubo automatically:
  1. Saves this to semantic memory via memory_write
  2. Creates KG entities: You (person), Alex (person), Horizon (project)
  3. Creates KG relations:
       You --works_on--> Horizon
       Alex --works_on--> Horizon
       You --role:frontend--> Horizon
       Alex --role:backend--> Horizon
  4. Next time you mention "Alex" or "Horizon", this context is
     auto-injected into the LLM prompt

This means you can teach Zubo facts naturally through conversation, and it will recall them when relevant — without being asked.

Creating Custom Agents

Custom agents are defined as directories inside ~/.zubo/workspace/agents/. Each directory contains a single AGENT.md file that specifies the agent's name, description, system prompt, and allowed tools.

Here is an example AGENT.md for a research specialist:

# research_agent
A specialized agent for web research and summarization.

## System Prompt
You are a research specialist. Focus on finding accurate, up-to-date
information from reliable sources. Always cite your sources and provide
concise summaries. When researching a topic, search from multiple angles
to ensure comprehensive coverage.

## Tools
- web_search
- url_fetch
- memory_write

There are three ways to create a custom agent:

• Manually — Create the directory and AGENT.md file yourself at ~/.zubo/workspace/agents/research_agent/AGENT.md.
• Conversationally — Tell Zubo: "Create an agent called research_agent that specializes in web research and has access to web_search, url_fetch, and memory_write." Zubo will generate the AGENT.md for you.
• Programmatically — Use the manage_agents tool to create, update, list, or delete agents.

Here is an example of creating and using an agent entirely through conversation:

You: Create an agent called "researcher" that can only search the web
     and fetch URLs. Its job is deep research.

Zubo: Created agent "researcher" with tools: web_search, url_fetch,
      http_request. System prompt focused on thorough research and
      source citation.

You: @researcher Find the top 3 competitors to Linear and compare
     their pricing

Zubo: [delegates to researcher agent]

      Here's a comparison of Linear's top competitors:

      1. Jira — Free tier for up to 10 users, Standard at $8.15/user/mo...
      2. Shortcut — Free for up to 10 members, Team at $8.50/user/mo...
      3. Asana — Free tier available, Premium at $10.99/user/mo...

      Sources: [jira.com, shortcut.com, asana.com]

Agents have restricted tool access — they can only use the tools explicitly listed in their ## Tools section. This is a key security and reliability feature: a research agent does not need access to your calendar, and a writing agent does not need access to the shell.

Agent Fields

Sub-Agent Delegation

The main agent can delegate tasks to sub-agents using the built-in delegate tool. When a task is delegated, the sub-agent runs with its own system prompt and restricted tool set, processes the task, and returns a result to the main agent.

Key rules for delegation:

• Maximum delegation depth: 2 — This prevents infinite recursion. The main agent (depth 0) can delegate to a sub-agent (depth 1), which can delegate once more (depth 2), but no further.
• Sub-agents cannot delegate further or access the manage_agents or delegate tools — These tools are automatically stripped from sub-agent tool lists to prevent abuse.
• Immutable security preamble — Every sub-agent's system prompt is prefixed with an immutable set of security rules that cannot be overridden by the user-defined agent prompt. These rules prevent sub-agents from revealing secrets, bypassing tool permission levels, delegating to other agents, or modifying their own configuration.
• Each delegation creates a separate session — This provides context isolation. The sub-agent's conversation history does not bleed into the main agent's context.
• Memory is shared — Sub-agents share the same memory store (semantic memory and knowledge graph) as the main agent. Research findings, facts, and knowledge graph entities written by a sub-agent are immediately available to the main agent and all other sub-agents.

Here is an example of how delegation works in practice:

User: "Research the latest AI news and summarize it"

Zubo (main agent):
  [Decides this is a research task, delegates to research_agent]

  research_agent:
    [Uses web_search to find recent AI articles]
    [Uses url_fetch to read the top 3 articles]
    [Uses memory_write to save key findings]
    Returns: "Here's a summary of today's AI news:
    1. OpenAI announced GPT-5 with improved reasoning...
    2. Google DeepMind published new results on...
    3. Meta released an open-source model that..."

Zubo (main agent):
  "Based on the research, here's what's happening in AI today:
   [Formats and presents the research_agent's findings]"

The user sees only the final response from the main agent. The delegation is transparent unless you inspect the logs in the dashboard.

Workflows

Workflows let you chain multiple agents together in a structured, multi-step pipeline. Each step defines a task, the agent that should handle it, and its dependencies on other steps. Zubo executes steps in dependency order using topological sorting, and independent steps run in parallel.

Workflows are defined as WORKFLOW.md files inside ~/.zubo/workspace/workflows/. Here is an example:

# content_pipeline
A workflow that researches, writes, and reviews content.

## Agents
- research_agent
- writer_agent
- reviewer_agent

## Steps
### research
- agent: research_agent
- task: Research the topic: $input

### write
- agent: writer_agent
- task: Write an article based on this research: $research
- dependsOn: research

### review
- agent: reviewer_agent
- task: Review and improve this article: $write
- dependsOn: write

In this example, the research step runs first. Once it completes, its output is passed to the write step via the $research variable. After writing is complete, the review step receives the article via $write and produces the final output.

Running a Workflow

There are two ways to trigger a workflow:

• Conversationally — Tell Zubo: "Run the content_pipeline workflow with input: AI trends in 2025"
• Programmatically — Use the run_workflow tool with the workflow name and input string.

Variables

Workflows use a simple variable system to pass data between steps:

• $input — The original input string provided when the workflow was triggered.
• $stepName — The output of a previously completed step. For example, $research contains the output of the research step.

Execution Details

• Steps are executed in topological order based on their dependsOn declarations.
• Steps with no dependencies (or whose dependencies are already satisfied) run in parallel.
• Each step has a maximum of 8 agent rounds to complete its task.
• Execution is logged in the database in the workflow_executions and workflow_step_logs tables for auditing and debugging.

Workflow Step Fields

Agent Teams

Teams provide a way to group related agents and associate them with a default workflow. They are defined as TEAM.md files inside ~/.zubo/workspace/teams/.

# content_team
A team for content creation workflows.

## Agents
- research_agent
- writer_agent
- reviewer_agent

## Default Workflow
content_pipeline

Teams serve as an organizational layer:

• They group agents that work together on related tasks.
• They associate a default workflow that is triggered when the team is invoked.
• They can be created and managed using the manage_teams tool or by asking Zubo conversationally.

When you tell Zubo "use the content team to write about AI trends," it automatically activates the team's default workflow with your input.

Best Practices

• Keep agents focused — Each agent should have a clear, narrow purpose. A "research_agent" that also edits code and manages calendars is doing too much.
• Limit tools per agent — Only give agents the tools they actually need. Fewer tools means less confusion for the LLM and fewer potential failure modes.
• Use workflows for multi-step processes — Rather than asking one agent to research, write, and review in a single turn, break it into a workflow with specialized agents for each step.
• Write clear system prompts — The more specific your agent's system prompt, the better it performs. Include examples of desired output format, tone, and behavior.
• Test agents individually — Before combining agents in a workflow, test each one in isolation to make sure it handles its task well.
• Don't over-engineer — The default agent handles most tasks well on its own. Only create custom agents when you have a genuine need for specialization, restricted tool access, or multi-step orchestration.