003 Name Skill B4e2adc3

---
name: building-agents-core
description: Core concepts for goal-driven agents - architecture, node types, tool discovery, and workflow overview. Use when starting agent development or need to understand agent fundamentals.
license: Apache-2.0
metadata:
  author: hive
  version: "1.0"
  type: foundational
  part_of: building-agents
---

# 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)

```python
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

```python
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

```python
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

```python
# 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)

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

### Step 2: Discover Available Tools

```python
# 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:

```json
{
  "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=[...]`:

1. Call `list_mcp_tools()` to get available tools
2. Check each tool in your node exists in the response
3. 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

```python
# 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
```python
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
```python
mcp__agent-builder__validate_graph()
# Returns: unreachable nodes, missing connections, etc.
```

**create_session** - Track session state for bookkeeping
```python
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