hive-concepts

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:

• event_loop — Multi-turn streaming loop with tool execution and judge-based evaluation. Works with or without tools.
• function — Deterministic Python operations. No LLM involved.

search_node = NodeSpec(
    id="search-web",
    name="Search Web",
    description="Search for information and extract results",
    node_type="event_loop",
    input_keys=["query"],
    output_keys=["search_results"],
    system_prompt="Search the web for: {query}. Use the web_search tool to find results, then call set_output to store them.",
    tools=["web_search"],
)