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