agent-builder

Continuum Agent Builder

Build agents as directed graphs where nodes are LLM steps and edges define execution flow.

Quick Start

Minimal agent structure:

{
  "id": "a1b2c3d4-e5f6-4789-abcd-1234567890ab",
  "name": "Agent Name",
  "description": "What this agent does",
  "generation_prompt": "Original user request",
  "response_format": { "type": 1, "payload": null },
  "nodes": [
    {
      "id": "b2c3d4e5-f6a7-4890-bcde-234567890abc",
      "name": "Process",
      "prompt": "Do the task.",
      "tools": [],
      "max_iterations": 3,
      "is_exit_node": true
    }
  ],
  "edges": [
    { "id": "c3d4e5f6-a7b8-4901-cdef-34567890abcd", "source": "START", "target": "b2c3d4e5-f6a7-4890-bcde-234567890abc", "condition_prompt": null },
    { "id": "d4e5f6a7-b8c9-4012-defa-4567890abcde", "source": "b2c3d4e5-f6a7-4890-bcde-234567890abc", "target": "END", "condition_prompt": null }
  ],
  "execution_plan": "graph TD\n    START([START]) --> process[Process]\n    process --> END([END])"
}

Note: Use UUIDs for all IDs, but keep execution_plan human-readable.

Discovery Scripts

Before building an agent, discover available data connections and tools.

List Data Connections

python scripts/fetch_data_connections.py [user_id]

Returns all configured MCP data connections with IDs needed for tool binding.

List Available Tools

python scripts/fetch_tools.py [user_id] [connection_name_filter]

Returns tools from all connections, or filter by connection name/ID.

Example:

python scripts/fetch_tools.py 181084522 todoist

Workflow

1. Understand Requirements

• What task does the agent perform?
• What inputs/outputs are expected?
• Run discovery scripts to see available tools/connections
• Does it need parallel processing or conditional logic?

2. Choose Pattern

Recommended: Parallel Reports → Apply

For content transformation tasks, use parallel analyzers that produce REPORTS (not modifications), then a final node applies all changes:

START → analyzeAspectA (report only) → applyChanges → END
START → analyzeAspectB (report only) ↗

Why: Each analyzer focuses on ONE thing, no cascading errors, final node has full context.

Pattern	Use When
Parallel Reports → Apply	Transforming/editing content (recommended default)
Linear Pipeline	Sequential steps with dependencies
Conditional Routing	Different paths based on input
Loop with Validation	Iterative refinement needed

See patterns.md for detailed examples.

3. Design Nodes

For each step:

• id: UUID format (a1b2c3d4-e5f6-4789-abcd-1234567890ab)
• name: Human-readable (Analyze Data)
• prompt: Clear instructions focused on outcomes, not tool mechanics
• tools: Only bindable tools with data_connection_id (system tools auto-available)
• is_exit_node: true for final user-facing node
• defer: true if waiting for parallel branches
• max_iterations: 1-10 based on expected tool calls

4. Connect Edges

• Start from START
• End at END
• Add condition_prompt for routing decisions (yes/no questions)
• Multiple edges from same source = parallel execution

5. Generate Mermaid

Create execution_plan showing the graph:

graph TD
    START([START]) --> nodeA[Node A]
    nodeA --> nodeB[Node B]
    nodeB --> END([END])

Node Prompt Guidelines

Prompt Writing Principles

1. Positive Framing — Say what TO DO, not what NOT to do

Bad:  "Don't include irrelevant details"
Good: "Focus only on [specific aspect]"

2. Context Over Commands — Explain WHY, not just WHAT

Bad:  "Output a report"
Good: "Output a report (this will be combined with other analyses in the final step)"

3. Use XML for Complex Instructions

<task>
Analyze fillers in the transcription
</task>

<output_format>
List each filler with surrounding context
</output_format>

<constraint>
Do NOT modify the original text
</constraint>

4. Be Explicit About Scope — Claude follows instructions literally

Bad:  "Clean the text"
Good: "Remove only the items identified in the reports. Keep everything else exactly as is."

Report Nodes (for Parallel Reports pattern)

Analyzer nodes produce REPORTS, NOT modifications:

<task>
Find [issues] in the input
</task>

<output>
Structured report: what found, where, suggested fix
</output>

<constraint>
Do NOT modify the text. Only produce the report.
</constraint>

Apply/Synthesize Node

Final node receives all reports:

<task>
Apply changes from ALL reports to the original
</task>

<rules>
- Apply each fix from the reports
- Keep everything else EXACTLY as is
- Do not add improvements beyond the reports
</rules>

<output>
The final result only
</output>

Outcome-Focused Prompts

Focus on WHAT to produce, not HOW to call tools. Let the agent discover and use tools naturally.

Good: "Generate a deal intelligence report with:
       - Executive summary
       - Company profiles with key metrics
       - Contact list with roles"

Bad:  "Call the DSL generator sub-agent with call_sub_agent tool..."

State Communication

Nodes share data via state tools (auto-available, don't mention in tools array):

"Analyze the input. Store results with set_state('analysis', your_findings)."

"Retrieve previous analysis with get_state(['analysis']). Build on those findings."

Response Formats

MARKDOWN (default)

{ "type": 1, "payload": null }

BLUEPRINT (structured)

{
  "type": 2,
  "payload": {
    "format": "JSON",
    "output_schema": { /* JSON Schema */ },
    "rules": "Additional formatting rules"
  }
}

References

• Schema Reference - Complete JSON schema with all fields
• Design Patterns - Common agent architectures with examples
• Tool Integration - System tools and MCP binding

Validation Checklist

Before finalizing:

• All IDs are UUIDs (nodes, edges, data_connections)
• Every node has unique id
• Edges connect all nodes (no orphans)
• Path from START to END exists
• Exit node marked with is_exit_node: true
• Deferred nodes have multiple incoming edges
• Every tool has non-null data_connection_id (no system tools in tools array)
• For type 2 response_format, exit node has appropriate tool (call_sub_agent if delegating)
• Mermaid diagram matches edges (use human-readable names, not UUIDs)
• Prompts focus on outcomes, not tool mechanics