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.

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.

Custom System Prompt

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 System Prompt panel in the web dashboard and edit it there. Changes are saved to SYSTEM.md automatically.

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.

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.

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.
• 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 can search and write to the same memory store as the main agent, so research findings and facts persist across delegations.

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.