Building Agents - Core Concepts

Foundational knowledge for building goal-driven agents as Python packages.

Architecture: Python Services (Not JSON Configs)

Agents are built as Python packages:

exports/my_agent/
├── __init__.py          # Package exports
├── __main__.py          # CLI (run, info, validate, shell)
├── agent.py             # Graph construction (goal, edges, agent class)
├── nodes/__init__.py    # Node definitions (NodeSpec)
├── config.py            # Runtime config
└── README.md            # Documentation

Key Principle: Agent is visible and editable during build

✅ Files created immediately as components are approved
✅ User can watch files grow in their editor
✅ No session state - just direct file writes
✅ No "export" step - agent is ready when build completes

Core Concepts

Goal

Success criteria and constraints (written to agent.py)

goal = Goal(
    id="research-goal",
    name="Technical Research Agent",
    description="Research technical topics thoroughly",
    success_criteria=[
        SuccessCriterion(
            id="completeness",
            description="Cover all aspects of topic",
            metric="coverage_score",
            target=">=0.9",
            weight=0.4,
        ),
        # 3-5 success criteria total
    ],
    constraints=[
        Constraint(
            id="accuracy",
            description="All information must be verified",
            constraint_type="hard",
            category="quality",
        ),
        # 1-5 constraints total
    ],
)

Node

Unit of work (written to nodes/init.py)

Node Types:

llm_generate - Text generation, parsing
llm_tool_use - Actions requiring tools
router - Conditional branching
function - Deterministic operations

search_node = NodeSpec(
    id="search-web",
    name="Search Web",
    description="Search for information online",
    node_type="llm_tool_use",
    input_keys=["query"],
    output_keys=["search_results"],
    system_prompt="Search the web for: {query}",
    tools=["web_search"],
    max_retries=3,
)

Edge

Connection between nodes (written to agent.py)

Edge Conditions:

on_success - Proceed if node succeeds
on_failure - Handle errors
always - Always proceed
conditional - Based on expression

EdgeSpec(
    id="search-to-analyze",
    source="search-web",
    target="analyze-results",
    condition=EdgeCondition.ON_SUCCESS,
    priority=1,
)

Pause/Resume

Multi-turn conversations

Pause nodes - Stop execution, wait for user input
Resume entry points - Continue from pause with user's response

# Example pause/resume configuration
pause_nodes = ["request-clarification"]
entry_points = {
    "start": "analyze-request",
    "request-clarification_resume": "process-clarification"
}

Tool Discovery & Validation

CRITICAL: Before adding a node with tools, you MUST verify the tools exist.

Tools are provided by MCP servers. Never assume a tool exists - always discover dynamically.

Step 1: Register MCP Server (if not already done)

mcp__agent-builder__add_mcp_server(
    name="tools",
    transport="stdio",
    command="python",
    args='["mcp_server.py", "--stdio"]',
    cwd="../tools"
)

Step 2: Discover Available Tools

# List all tools from all registered servers
mcp__agent-builder__list_mcp_tools()

# Or list tools from a specific server
mcp__agent-builder__list_mcp_tools(server_name="tools")

This returns available tools with their descriptions and parameters:

{
  "success": true,
  "tools_by_server": {
    "tools": [
      {
        "name": "web_search",
        "description": "Search the web...",
        "parameters": ["query"]
      },
      {
        "name": "web_scrape",
        "description": "Scrape a URL...",
        "parameters": ["url"]
      }
    ]
  },
  "total_tools": 14
}

Step 3: Validate Before Adding Nodes

Before writing a node with tools=[...]:

Call list_mcp_tools() to get available tools
Check each tool in your node exists in the response
If a tool doesn't exist:
- DO NOT proceed with the node
- Inform the user: "The tool 'X' is not available. Available tools are: ..."
- Ask if they want to use an alternative or proceed without the tool

Tool Validation Anti-Patterns

❌ Never assume a tool exists - always call list_mcp_tools() first ❌ Never write a node with unverified tools - validate before writing ❌ Never silently drop tools - if a tool doesn't exist, inform the user ❌ Never guess tool names - use exact names from discovery response

Example Validation Flow

# 1. User requests: "Add a node that searches the web"
# 2. Discover available tools
tools_response = mcp__agent-builder__list_mcp_tools()

# 3. Check if web_search exists
available = [t["name"] for tools in tools_response["tools_by_server"].values() for t in tools]
if "web_search" not in available:
    # Inform user and ask how to proceed
    print("❌ 'web_search' not available. Available tools:", available)
else:
    # Proceed with node creation
    # ...

Workflow Overview: Incremental File Construction

1. CREATE PACKAGE → mkdir + write skeletons
2. DEFINE GOAL → Write to agent.py + config.py
3. FOR EACH NODE:
   - Propose design
   - User approves
   - Write to nodes/__init__.py IMMEDIATELY ← FILE WRITTEN
   - (Optional) Validate with test_node ← MCP VALIDATION
   - User can open file and see it
4. CONNECT EDGES → Update agent.py ← FILE WRITTEN
   - (Optional) Validate with validate_graph ← MCP VALIDATION
5. FINALIZE → Write agent class to agent.py ← FILE WRITTEN
6. DONE - Agent ready at exports/my_agent/

Files written immediately. MCP tools optional for validation/testing bookkeeping.

The Key Difference

OLD (Bad):

MCP add_node → Session State → MCP add_node → Session State → ...
                                                                ↓
                                                     MCP export_graph
                                                                ↓
                                                       Files appear

NEW (Good):

Write node to file → (Optional: MCP test_node) → Write node to file → ...
       ↓                                               ↓
  File visible                                    File visible
  immediately                                     immediately

Bottom line: Use Write/Edit for construction, MCP for validation if needed.

When to Use This Skill

Use building-agents-core when:

Starting a new agent project and need to understand fundamentals
Need to understand agent architecture before building
Want to validate tool availability before proceeding
Learning about node types, edges, and graph execution

Next Steps:

Ready to build? → Use building-agents-construction skill
Need patterns and examples? → Use building-agents-patterns skill

MCP Tools for Validation

After writing files, optionally use MCP tools for validation:

test_node - Validate node configuration with mock inputs

mcp__agent-builder__test_node(
    node_id="search-web",
    test_input='{"query": "test query"}',
    mock_llm_response='{"results": "mock output"}'
)

validate_graph - Check graph structure

mcp__agent-builder__validate_graph()
# Returns: unreachable nodes, missing connections, etc.

create_session - Track session state for bookkeeping

mcp__agent-builder__create_session(session_name="my-build")

Key Point: Files are written FIRST. MCP tools are for validation only.

Related Skills

building-agents-construction - Step-by-step building process
building-agents-patterns - Best practices and examples
agent-workflow - Complete workflow orchestrator
testing-agent - Test and validate completed agents