# Claude Code setup Source: https://docs.adenhq.com/building-agent/ai-tools/claude-code Configure Claude Code for your documentation workflow Claude Code is Anthropic's official CLI tool. This guide will help you set up Claude Code to help you write and maintain your documentation. ## Prerequisites * Active Claude subscription (Pro, Max, or API access) ## Setup 1. Install Claude Code globally: ```bash theme={null} npm install -g @anthropic-ai/claude-code ``` 2. Navigate to your docs directory. 3. (Optional) Add the `CLAUDE.md` file below to your project. 4. Run `claude` to start. ## Create `CLAUDE.md` Create a `CLAUDE.md` file at the root of your documentation repository to train Claude Code on your specific documentation standards: ```markdown theme={null} # Mintlify documentation ## Working relationship - You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so - ALWAYS ask for clarification rather than making assumptions - NEVER lie, guess, or make up information ## Project context - Format: MDX files with YAML frontmatter - Config: docs.json for navigation, theme, settings - Components: Mintlify components ## Content strategy - Document just enough for user success - not too much, not too little - Prioritize accuracy and usability of information - Make content evergreen when possible - Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason - Check existing patterns for consistency - Start by making the smallest reasonable changes ## Frontmatter requirements for pages - title: Clear, descriptive page title - description: Concise summary for SEO/navigation ## Writing standards - Second-person voice ("you") - Prerequisites at start of procedural content - Test all code examples before publishing - Match style and formatting of existing pages - Include both basic and advanced use cases - Language tags on all code blocks - Alt text on all images - Relative paths for internal links ## Git workflow - NEVER use --no-verify when committing - Ask how to handle uncommitted changes before starting - Create a new branch when no clear branch exists for changes - Commit frequently throughout development - NEVER skip or disable pre-commit hooks ## Do not - Skip frontmatter on any MDX file - Use absolute URLs for internal links - Include untested code examples - Make assumptions - always ask for clarification ``` # OpenAI Codex CLI setup Source: https://docs.adenhq.com/building-agent/ai-tools/codex Configure OpenAI Codex CLI as a supported coding agent for Hive This guide documents Codex CLI support in Hive and how to use it alongside existing Claude Code and Cursor workflows. ## What This Adds Codex support includes: * A `.codex/` configuration model * MCP server connections for `agent-builder` and `tools` * Instruction files mirroring Hive build/test workflows This aligns with the same workflow goals as existing coding-agent integrations. ## Expected Project Structure ```text theme={null} .codex/ ├── config.json ├── mcp_servers.json └── instructions/ ├── hive.md ├── hive-create.md ├── hive-concepts.md ├── hive-patterns.md ├── hive-test.md └── hive-credentials.md ``` ## MCP Server Configuration Use `.codex/mcp_servers.json`: ```json theme={null} { "mcpServers": { "agent-builder": { "command": "python", "args": ["-m", "framework.mcp.agent_builder_server"], "cwd": "core", "env": { "PYTHONPATH": "../tools/src" } }, "tools": { "command": "python", "args": ["mcp_server.py", "--stdio"], "cwd": "tools", "env": { "PYTHONPATH": "src" } } } } ``` ## Instruction Files Mirror the existing Hive skill set into Codex instruction files: * `hive` for full build workflow * `hive-create` for creation flow * `hive-concepts` for conceptual guidance * `hive-patterns` for architecture best practices * `hive-test` for test-generation and validation * `hive-credentials` for credential setup/sync guidance Keep instruction intent consistent with Claude/Cursor variants, but adapt syntax to Codex’s instruction model. ## Verification Checklist After setup, verify: 1. Codex can connect to `agent-builder` MCP server. 2. Codex can connect to `tools` MCP server. 3. Hive instruction workflows are invokable from Codex. 4. End-to-end agent creation/testing runs successfully. ## Quick Validation Steps ```bash theme={null} # From hive root ./quickstart.sh # Then launch Codex CLI and verify MCP-backed workflows codex ``` Use a small test goal first and confirm: * graph generation works * test scaffolding is created * tool calls route through MCP correctly ## Troubleshooting ### MCP server not visible * Confirm `.codex/mcp_servers.json` path and JSON validity * Validate `cwd` and `PYTHONPATH` values * Ensure dependencies are installed via `./quickstart.sh` ### Instructions not recognized * Confirm files exist under `.codex/instructions/` * Verify naming matches expected invocation names ### Python command failures * Run from Hive root * Ensure Python/uv environment is healthy ## Related * [Claude Code setup](/building-agent/ai-tools/claude-code) * [Cursor setup](/building-agent/ai-tools/cursor) * [Build Your First Agent](/building/first-agent) # Cursor setup Source: https://docs.adenhq.com/building-agent/ai-tools/cursor Configure Cursor for your documentation workflow Use Cursor to help write and maintain your documentation. This guide shows how to configure Cursor for better results on technical writing tasks and using Mintlify components. ## Prerequisites * Cursor editor installed * Access to your documentation repository ## Project rules Create project rules that all team members can use. In your documentation repository root: ```bash theme={null} mkdir -p .cursor ``` Create `.cursor/rules.md`: ````markdown theme={null} # Mintlify technical writing rule You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices. ## Core writing principles ### Language and style requirements - Use clear, direct language appropriate for technical audiences - Write in second person ("you") for instructions and procedures - Use active voice over passive voice - Employ present tense for current states, future tense for outcomes - Avoid jargon unless necessary and define terms when first used - Maintain consistent terminology throughout all documentation - Keep sentences concise while providing necessary context - Use parallel structure in lists, headings, and procedures ### Content organization standards - Lead with the most important information (inverted pyramid structure) - Use progressive disclosure: basic concepts before advanced ones - Break complex procedures into numbered steps - Include prerequisites and context before instructions - Provide expected outcomes for each major step - Use descriptive, keyword-rich headings for navigation and SEO - Group related information logically with clear section breaks ### User-centered approach - Focus on user goals and outcomes rather than system features - Anticipate common questions and address them proactively - Include troubleshooting for likely failure points - Write for scannability with clear headings, lists, and white space - Include verification steps to confirm success ## Mintlify component reference ### Callout components #### Note - Additional helpful information Supplementary information that supports the main content without interrupting flow #### Tip - Best practices and pro tips Expert advice, shortcuts, or best practices that enhance user success #### Warning - Important cautions Critical information about potential issues, breaking changes, or destructive actions #### Info - Neutral contextual information Background information, context, or neutral announcements #### Check - Success confirmations Positive confirmations, successful completions, or achievement indicators ### Code components #### Single code block Example of a single code block: ```javascript config.js const apiConfig = { baseURL: 'https://api.example.com', timeout: 5000, headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` } }; ``` #### Code group with multiple languages Example of a code group: ```javascript Node.js const response = await fetch('/api/endpoint', { headers: { Authorization: `Bearer ${apiKey}` } }); ``` ```python Python import requests response = requests.get('/api/endpoint', headers={'Authorization': f'Bearer {api_key}'}) ``` ```curl cURL curl -X GET '/api/endpoint' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` #### Request/response examples Example of request/response documentation: ```bash cURL curl -X POST 'https://api.example.com/users' \ -H 'Content-Type: application/json' \ -d '{"name": "John Doe", "email": "john@example.com"}' ``` ```json Success { "id": "user_123", "name": "John Doe", "email": "john@example.com", "created_at": "2024-01-15T10:30:00Z" } ``` ### Structural components #### Steps for procedures Example of step-by-step instructions: Run `npm install` to install required packages. Verify installation by running `npm list`. Create a `.env` file with your API credentials. ```bash API_KEY=your_api_key_here ``` Never commit API keys to version control. #### Tabs for alternative content Example of tabbed content: ```bash brew install node npm install -g package-name ``` ```powershell choco install nodejs npm install -g package-name ``` ```bash sudo apt install nodejs npm npm install -g package-name ``` #### Accordions for collapsible content Example of accordion groups: - **Firewall blocking**: Ensure ports 80 and 443 are open - **Proxy configuration**: Set HTTP_PROXY environment variable - **DNS resolution**: Try using 8.8.8.8 as DNS server ```javascript const config = { performance: { cache: true, timeout: 30000 }, security: { encryption: 'AES-256' } }; ``` ### Cards and columns for emphasizing information Example of cards and card groups: Complete walkthrough from installation to your first API call in under 10 minutes. Learn how to authenticate requests using API keys or JWT tokens. Understand rate limits and best practices for high-volume usage. ### API documentation components #### Parameter fields Example of parameter documentation: Unique identifier for the user. Must be a valid UUID v4 format. User's email address. Must be valid and unique within the system. Maximum number of results to return. Range: 1-100. Bearer token for API authentication. Format: `Bearer YOUR_API_KEY` #### Response fields Example of response field documentation: Unique identifier assigned to the newly created user. ISO 8601 formatted timestamp of when the user was created. List of permission strings assigned to this user. #### Expandable nested fields Example of nested field documentation: Complete user object with all associated data. User profile information including personal details. User's first name as entered during registration. URL to user's profile picture. Returns null if no avatar is set. ### Media and advanced components #### Frames for images Wrap all images in frames: Main dashboard showing analytics overview Analytics dashboard with charts #### Videos Use the HTML video element for self-hosted video content: Embed YouTube videos using iframe elements: #### Tooltips Example of tooltip usage: API #### Updates Use updates for changelogs: ## New features - Added bulk user import functionality - Improved error messages with actionable suggestions ## Bug fixes - Fixed pagination issue with large datasets - Resolved authentication timeout problems ## Required page structure Every documentation page must begin with YAML frontmatter: ```yaml --- title: "Clear, specific, keyword-rich title" description: "Concise description explaining page purpose and value" --- ``` ## Content quality standards ### Code examples requirements - Always include complete, runnable examples that users can copy and execute - Show proper error handling and edge case management - Use realistic data instead of placeholder values - Include expected outputs and results for verification - Test all code examples thoroughly before publishing - Specify language and include filename when relevant - Add explanatory comments for complex logic - Never include real API keys or secrets in code examples ### API documentation requirements - Document all parameters including optional ones with clear descriptions - Show both success and error response examples with realistic data - Include rate limiting information with specific limits - Provide authentication examples showing proper format - Explain all HTTP status codes and error handling - Cover complete request/response cycles ### Accessibility requirements - Include descriptive alt text for all images and diagrams - Use specific, actionable link text instead of "click here" - Ensure proper heading hierarchy starting with H2 - Provide keyboard navigation considerations - Use sufficient color contrast in examples and visuals - Structure content for easy scanning with headers and lists ## Component selection logic - Use **Steps** for procedures and sequential instructions - Use **Tabs** for platform-specific content or alternative approaches - Use **CodeGroup** when showing the same concept in multiple programming languages - Use **Accordions** for progressive disclosure of information - Use **RequestExample/ResponseExample** specifically for API endpoint documentation - Use **ParamField** for API parameters, **ResponseField** for API responses - Use **Expandable** for nested object properties or hierarchical information ```` # Windsurf setup Source: https://docs.adenhq.com/building-agent/ai-tools/windsurf Configure Windsurf for your documentation workflow Configure Windsurf's Cascade AI assistant to help you write and maintain documentation. This guide shows how to set up Windsurf specifically for your Mintlify documentation workflow. ## Prerequisites * Windsurf editor installed * Access to your documentation repository ## Workspace rules Create workspace rules that provide Windsurf with context about your documentation project and standards. Create `.windsurf/rules.md` in your project root: ````markdown theme={null} # Mintlify technical writing rule ## Project context - This is a documentation project on the Mintlify platform - We use MDX files with YAML frontmatter - Navigation is configured in `docs.json` - We follow technical writing best practices ## Writing standards - Use second person ("you") for instructions - Write in active voice and present tense - Start procedures with prerequisites - Include expected outcomes for major steps - Use descriptive, keyword-rich headings - Keep sentences concise but informative ## Required page structure Every page must start with frontmatter: ```yaml --- title: "Clear, specific title" description: "Concise description for SEO and navigation" --- ``` ## Mintlify components ### Callouts - `` for helpful supplementary information - `` for important cautions and breaking changes - `` for best practices and expert advice - `` for neutral contextual information - `` for success confirmations ### Code examples - When appropriate, include complete, runnable examples - Use `` for multiple language examples - Specify language tags on all code blocks - Include realistic data, not placeholders - Use `` and `` for API docs ### Procedures - Use `` component for sequential instructions - Include verification steps with `` components when relevant - Break complex procedures into smaller steps ### Content organization - Use `` for platform-specific content - Use `` for progressive disclosure - Use `` and `` for highlighting content - Wrap images in `` components with descriptive alt text ## API documentation requirements - Document all parameters with `` - Show response structure with `` - Include both success and error examples - Use `` for nested object properties - Always include authentication examples ## Quality standards - Test all code examples before publishing - Use relative paths for internal links - Include alt text for all images - Ensure proper heading hierarchy (start with h2) - Check existing patterns for consistency ```` # Agent Architecture Source: https://docs.adenhq.com/building-agent/concepts/agent-architecture Understanding nodes, edges, and the agent graph structure ## Agent Graph Overview Every Aden agent is represented as a directed graph consisting of: * **Nodes** - Individual processing units (LLM calls, routers, functions, human intervention) * **Edges** - Connections between nodes that define flow (success, failure, conditional) * **Context** - Shared state passed between nodes (memory, tools, LLM access) ```mermaid theme={null} flowchart LR subgraph AGENT["Agent Graph"] A["LLM Node"] -->|on_success| B["Router Node"] A -->|on_failure| E["Error Handler"] B -->|condition: urgent| C["Human Node"] B -->|condition: standard| D["Function Node"] end ``` ## Node Types ### LLM Node Executes a language model call with a prompt template and context. ```python theme={null} { "type": "llm", "name": "analyze_request", "model": "claude-sonnet-4-5-20250929", "prompt": "Analyze this customer request: {{input}}", "output_schema": {...} } ``` **Capabilities:** * Structured output via JSON schema * Tool/function calling * Streaming responses * Automatic retry with backoff ### Router Node Routes execution to different paths based on conditions or LLM decisions. ```python theme={null} { "type": "router", "name": "urgency_router", "conditions": [ {"path": "urgent_handler", "when": "urgency == 'high'"}, {"path": "standard_handler", "when": "urgency == 'low'"}, {"path": "review_handler", "default": true} ] } ``` **Routing Strategies:** * **Conditional** - Based on output values * **LLM-decided** - Let the model choose the path * **Weighted** - Probabilistic routing for A/B testing ### Function Node Executes custom Python code for business logic, API calls, or data transformation. ```python theme={null} { "type": "function", "name": "send_email", "handler": "tools.send_email", "inputs": ["recipient", "subject", "body"] } ``` ### Human-in-the-Loop Node Pauses execution for human input with configurable timeouts and escalation. ```python theme={null} { "type": "human", "name": "manager_approval", "prompt": "Approve refund of ${{amount}}?", "timeout": "24h", "escalation": "auto_reject" } ``` See [Human-in-the-Loop](/building/human-in-the-loop) for details. ## Edge Types Edges connect nodes and define the execution flow: | Edge Type | Description | Example | | ------------- | ---------------------------------------- | --------------------- | | `on_success` | Execute when node completes successfully | LLM response received | | `on_failure` | Execute when node fails | API error, timeout | | `conditional` | Execute based on output conditions | `when: "score > 0.8"` | ```python theme={null} { "edges": [ {"from": "analyze", "to": "approve", "type": "on_success"}, {"from": "analyze", "to": "retry", "type": "on_failure"}, {"from": "router", "to": "path_a", "when": "category == 'A'"}, {"from": "router", "to": "path_b", "when": "category == 'B'"} ] } ``` ## SDK-Wrapped Nodes Every node in Aden is wrapped with the SDK, providing: Access to global and local memory stores Built-in access to configured LLM providers Access to MCP tools and custom functions Automatic logging, tracing, and cost tracking ## Node Context Each node receives a context object with: ```python theme={null} class NodeContext: memory: MemoryStore # Shared memory across nodes llm: LLMClient # Configured LLM client tools: ToolRegistry # Available tools input: dict # Input from previous node metadata: dict # Run metadata (trace_id, etc.) ``` ## Agent Specification Agents are defined in a JSON specification (`agent.json`): ```json theme={null} { "name": "support-agent", "version": "1.0.0", "goal": "Handle customer support tickets efficiently", "nodes": [...], "edges": [...], "config": { "default_model": "claude-sonnet-4-5-20250929", "timeout": "5m", "max_retries": 3 } } ``` ## Next Steps Dive into graph execution, routing patterns, and shared memory behavior Understand sessions, iterations, and headless runtime operations Create an agent from scratch Detailed node configuration options # Agent Graph Source: https://docs.adenhq.com/building-agent/concepts/agent-graph How nodes, edges, shared memory, and HITL form Hive runtime behavior ## Why a Graph Business workflows are rarely linear. Hive models execution as a directed graph so agents can branch, retry, loop, and escalate. ## Nodes Nodes are units of work that read from shared memory, perform logic, and write outputs. Core node types: * `event_loop`: multi-turn LLM + tools loop (primary autonomous workhorse) * `function`: deterministic Python logic * `router`: rule-based or model-assisted path selection * `human_input`: pause for supervised input * `llm_tool_use` and `llm_generate`: simpler one-shot LLM nodes ### Self-Correction in `event_loop` Each iteration can end with: * Accept * Retry * Escalate This reflexive loop improves within-session reliability without restarting the full run. ## Edges Edges define control flow: * On success * On failure * Conditional * LLM-decided Edges can also map outputs to downstream inputs and enable parallel branches. ## Shared Memory Shared memory is session-scoped state used for cross-node communication. * Nodes declare read/write contracts * Execution remains traceable and structured * Final state represents run output and side effects ## Human-in-the-Loop HITL nodes pause execution and preserve session state until a human responds. Use HITL for high-impact actions (financial operations, outbound communications, approvals). ## Graph Shape Example ```text theme={null} intake -> research -> draft -> [human review] -> send -> done ^ | +------------ on failure -------------+ ``` ## Related Concepts * [Goals and Outcomes](/building-agent/concepts/goals-outcomes) * [Worker Agent](/building-agent/concepts/worker-agent) * [Evolution](/building-agent/concepts/evolution) # Evolution Source: https://docs.adenhq.com/building-agent/concepts/evolution How Hive uses failure data to iteratively improve agent behavior ## Evolution vs Adaptiveness Evolution is the mechanism. Adaptiveness is the result. Hive captures failure data and uses coding-agent driven changes to produce better next versions. ## Evolution Loop 1. Execute: agent runs on real inputs 2. Evaluate: outcomes are checked against criteria and constraints 3. Diagnose: failure is localized to nodes, criteria, and decision traces 4. Regenerate: graph/prompts/tools/edges are revised and redeployed ## What Can Evolve * Prompts and instructions * Graph structure * Edge conditions * Tool selection * Constraint and criteria tuning ## Key Distinction Evolution does not imply general intelligence gains. It increases reliability for observed failure patterns over generations. ## Why Logging Matters Evolution quality depends on runtime evidence: * Node-level traces * Decision logs * Tool invocation outcomes * Cost and latency metrics Without this, changes are guesswork. ## Operational Guidance * Treat every production failure as test input for the next iteration * Capture reproducible failure context * Add regression coverage before redeploying > **Evolution in Practice**: Evolution is the engine of the iterate phase in Aden Hive's developer success cycle. Once your agent is deployed, [iteration strategies](/building/iteration) show you how to use production data to automatically improve agent behavior over time. ## Related Concepts * [Goals and Outcomes](/building-agent/concepts/goals-outcomes) * [Agent Graph](/building-agent/concepts/agent-graph) * [Worker Agent](/building-agent/concepts/worker-agent) * [Iteration](/building/iteration) # Goals and Outcomes Source: https://docs.adenhq.com/building-agent/concepts/goals-outcomes Define measurable success criteria, constraints, and context for Hive agents ## The Core Idea Hive is outcome-driven: you define what success looks like, and the agent adapts toward that result. Instead of hardcoding every step, you define: * A goal * Success criteria (weighted quality checks) * Constraints (hard and soft boundaries) * Context (domain knowledge and preferences) ## Task-Driven vs Goal-Driven vs Outcome-Driven | Paradigm | Main Question | Limitation | | -------------- | ------------------------------------ | ------------------------------------------------ | | Task-Driven | "Did each step run?" | Correct steps can still produce poor results | | Goal-Driven | "Are we aiming correctly?" | Goals can be vague without measurable criteria | | Outcome-Driven | "Did we produce the desired result?" | Requires clear metrics and evaluation discipline | ## Goal as a Structured Contract In Hive, a goal is a structured object with three parts. ### Success Criteria Each criterion defines a measurable quality signal and a weight. Common metrics: * `output_contains` * `output_equals` * `llm_judge` * `custom` Weights allow trade-offs across multiple quality dimensions. ### Constraints Constraints define non-negotiables and preferences. * Hard constraints: violation triggers failure/escalation * Soft constraints: violation is tolerated with warning/replan Typical categories: * `time` * `cost` * `safety` * `scope` * `quality` ### Context Context supplies durable background information that should influence agent decisions and LLM behavior. ## Why This Model Matters 1. The agent can self-correct during execution against explicit criteria. 2. Evolution has a target because failures map to specific unmet criteria. 3. Humans retain control through hard constraints and intervention gates. ## Goal Lifecycle Goals typically move through: `DRAFT -> READY -> ACTIVE -> COMPLETED | FAILED | SUSPENDED` ## Related Concepts * [Outcome-Driven Development](/building-agent/concepts/outcome-driven-development) * [Agent Graph](/building-agent/concepts/agent-graph) * [Evolution](/building-agent/concepts/evolution) # Outcome-Driven Development Source: https://docs.adenhq.com/building-agent/concepts/outcome-driven-development From intent to observed results - a precise framework for building agents that deliver measurable value ## What is Outcome-Driven Development? Outcome-driven development is a methodology where you define what success looks like, generate tests as hypotheses, and observe real outcomes at every stage. Unlike traditional approaches that focus on implementation details, ODD keeps you anchored to measurable results. The key insight: **tests produce outcomes, but they are experimental outcomes whose validity is bounded by the test context.** ## The Progression: From Intent to Outcomes ```mermaid theme={null} flowchart TD GOAL["Goal
Intent & Direction"] --> CRITERIA["Criteria
Success + Constraints"] CRITERIA --> TESTS["Tests
Hypotheses about outcomes"] TESTS --> TEST_OUTCOMES["Test Outcomes
Controlled environment"] TEST_OUTCOMES --> OPS_OUTCOMES["Operational Outcomes
Staging & pilot"] OPS_OUTCOMES --> REAL_OUTCOMES["Real-World Outcomes
Production & business value"] REAL_OUTCOMES -.->|"Feedback loop"| GOAL ``` ### 1. Start with a Goal A goal is **intent, direction, and preference**. No outcomes yet - only what you want to achieve. ``` "Build an agent that resolves Tier-1 support tickets reliably." ``` At this stage, you have expressed direction but haven't defined what success means or observed any results. ### 2. Define Criteria Criteria translate intent into **what winning would look like**. They set expectations but still aren't outcomes. In our framework, there are two types of criteria: * **Success Criteria:** Measurable conditions that define success. * **Constraints:** Conditions that define failure. #### Success Criteria Defined in `goal.py`, each `SuccessCriterion` represents a measurable condition: | Field | Purpose | | -------- | ------------------------------------------------------------------------- | | `metric` | How to measure: `output_contains`, `output_equals`, `llm_judge`, `custom` | | `target` | The expected value or condition | | `weight` | Relative importance (0-1) | ```python theme={null} SuccessCriterion( id="sc-kb-grounded", description="Answers are grounded in knowledge base content", metric="llm_judge", target="answers reference KB sources", weight=0.3, ) ``` #### Constraints Also in `goal.py`, `Constraint` defines boundaries the agent must respect: | Constraint Type | Behavior | | --------------- | ----------------------------- | | **Hard** | Violation = immediate failure | | **Soft** | Discouraged but allowed | | Category | Example | | --------- | ----------------------------------- | | `time` | Response within 30 seconds | | `cost` | Less than \$0.20 per request | | `safety` | No PII in responses | | `scope` | Only answer questions about billing | | `quality` | Hallucination rate below 5% | Criteria are expectations - measurable thresholds that define success and failure. ### 3. Generate Tests Tests are **hypotheses about outcomes**. Each test implicitly says: > "If the system behaves correctly, outcome X should occur under condition Y." Tests are measurement instruments, not outcomes themselves. They encode your assumptions about what correct behavior looks like. ```python theme={null} # This is a hypothesis, not yet an outcome def test_common_question_resolution(): """Agent should resolve common billing questions without escalation.""" result = agent.run({"question": "How do I update my payment method?"}) assert result.resolved == True assert result.escalated == False ``` ### 4. Run Tests → Observe Outcomes When you run tests, you finally have **outcomes**. But be precise about what kind: These are **observed outcomes in a controlled environment**. | What You Observe | Example | | ---------------- | -------------------------- | | Pass/fail rates | 47/50 tests passing | | Error modes | Timeout on complex queries | | Latency | P95 at 2.3 seconds | | Tool misuse | Called wrong API 3 times | | Hallucinations | 2 cases from edge prompts | **Why these are outcomes:** Something actually happened. The system interacted with inputs. Effects were observed, not imagined. **Why they're limited:** They don't yet tell you whether users trust the agent, whether it reduces real workload, or whether edge cases in the wild dominate behavior. ## Outcome Structure Defined in `decision.py`, the `Outcome` class captures everything about an execution result: ```python theme={null} class Outcome(BaseModel): success: bool # Did it succeed? result: Any # Actual output error: str | None # Error if failed state_changes: dict # Side effects tokens_used: int # LLM tokens consumed latency_ms: int # Execution time summary: str # Human-readable narrative ``` The framework tracks **what should happen** (criteria/constraints) and **what actually happened** (outcomes), then evaluates the gap. ## The Feedback Loop Outcome-driven development depends on closing the loop: ```mermaid theme={null} flowchart LR subgraph DEFINE["Define"] G["Goal"] --> C["Criteria"] end subgraph MEASURE["Measure"] C --> T["Tests"] T --> O["Outcomes"] end subgraph ADAPT["Adapt"] O --> U["Update"] end U -.->|"Refine system"| T U -.->|"Adjust criteria"| C U -.->|"Revisit goal (Only with Developer Intervention)"| G ``` Outcomes inform updates at every level: * **Update the system** - Fix bugs, improve prompts, add guardrails * **Adjust criteria** - Thresholds may be too strict or too lenient * **Revisit the goal** - Sometimes the original intent was not accurate or not up to date. Developer need to revisit and update the goal accoding to the outcomes. However, the framework should not be able to change the original goal to ensure the goal is consistent and respected. ## The Outcome Taxonomy All results are outcomes - they differ by **context and validity**, not by kind. | Stage | What You Observe | Outcome Type | | ------------------- | ----------------------------------------------- | -------------------- | | **Tests** | Pass/fail, errors, timings | Test outcomes | | **Staging / Pilot** | Task completion, escalations, user feedback | Operational outcomes | | **Production** | Behavior change, value created, business impact | Real-world outcomes | ### Test Outcomes Controlled environment. Known inputs. Repeatable conditions. * High internal validity * Limited external validity * Fast feedback loop * Low cost to observe ### Operational Outcomes Real users in limited deployment. Shadow mode or pilot groups. * Moderate internal validity * Growing external validity * Reveals integration issues * Surface unexpected edge cases ### Real-World Outcomes Full production. Business metrics. User trust. * Full external validity * Highest signal quality * Slowest feedback loop * Highest cost to observe ## Example: Support Agent Development ### Phase 1: Define **Goal:** ``` Build an agent that handles Tier-1 support tickets reliably. ``` **Success Criteria:** ```python theme={null} [ SuccessCriterion( id="sc-resolution", description="Resolves tickets without escalation", metric="custom", target="resolution_rate >= 0.6", weight=0.4, ), SuccessCriterion( id="sc-accuracy", description="Responses are factually correct", metric="llm_judge", target="no hallucinations or misinformation", weight=0.3, ), SuccessCriterion( id="sc-escalation", description="Escalates appropriately when needed", metric="custom", target="escalation_accuracy >= 0.9", weight=0.3, ), ] ``` **Constraints:** ```python theme={null} [ Constraint(type="hard", category="cost", value="cost_per_ticket < 0.20"), Constraint(type="hard", category="safety", value="no_pii_in_responses"), Constraint(type="soft", category="time", value="response_time < 30s"), ] ``` ### Phase 2: Test Outcomes Run automated tests against synthetic tickets. Each test produces an `Outcome`: ```python theme={null} Outcome( success=True, result={"answer": "To reset your password, go to Settings > Security..."}, error=None, state_changes={"ticket_status": "resolved"}, tokens_used=847, latency_ms=1230, summary="Resolved password reset question correctly" ) ``` **Aggregate results across test suite:** | Criterion | Result | Status | Judgment | | --------------------- | ------ | ---------------------------- | -------- | | Resolution rate | 52% | Below 60% target | `REPLAN` | | Accuracy (llm\_judge) | 97% | Passing | `ACCEPT` | | Cost per ticket | \$0.18 | Below \$0.20 hard constraint | `ACCEPT` | | Escalation accuracy | 87% | Below 90% target | `RETRY` | **Weighted score:** 78% (below 90% threshold) **Insight:** Resolution and escalation need work. The `HybridJudge` recommends `REPLAN` - adjust prompts, add examples. ### Phase 3: Operational Outcomes Deploy to 5% of traffic in shadow mode: | Metric | Result | Insight | | ------------------ | -------- | ------------------- | | Resolution rate | 58% | Closer to target | | User satisfaction | 3.8/5 | New signal | | Edge case failures | 12 types | Unexpected patterns | **Insight:** Real traffic reveals edge cases tests missed. Update test suite. ### Phase 4: Real-World Outcomes Full production deployment: | Metric | Result | Business Impact | | ---------------------- | ------- | --------------- | | Resolution rate | 63% | Target exceeded | | Support cost reduction | 34% | Direct savings | | Customer satisfaction | +12 NPS | Trust building | ## Best Practices Higher weights on critical criteria ensure the 90% threshold reflects true success Cost limits, PII protection, and scope boundaries should be hard constraints Use `llm_judge` metric for quality criteria that can't be measured programmatically ACCEPT, RETRY, REPLAN, ESCALATE - let the HybridJudge guide the response ## Next Steps See the canonical goal model used by Hive runtime and evaluation Understand how outcome gaps drive iterative agent improvement Learn about nodes, edges, and the agent graph structure Create your first outcome-driven agent # What is Aden? Source: https://docs.adenhq.com/building-agent/concepts/overview Build reliable, adaptive agents with goal-driven development centered on developer success ## Overview Aden is the platform, and Hive is the open framework for building agents that adapt toward outcomes. Instead of hardcoding workflow logic, you define goals, constraints, and context, then iterate based on observed results. This goal-driven approach powers developer success through a complete lifecycle: **create → debug → maintain → deploy → iterate**. > **Developer Success Path**: Aden Hive is purpose-built for developers who need reliable agents in production. [Learn who Hive is for](/getting-started/who-is-hive-for) and how it simplifies the journey from prototype to stable operations. Define goals and let the coding agent generate graph-based implementations Run agents with observability, retries, and guardrails in place Use failures and outcomes to improve agent behavior over time Insert human checkpoints where autonomous behavior needs supervision ## The Aden Advantage | Traditional Frameworks | Aden + Hive | | ---------------------- | ----------------------------------- | | Hardcoded workflows | Goal-driven graph generation | | Static behavior | Outcome-based adaptation | | Manual fallback wiring | Built-in routing and retries | | Limited supervision | First-class human-in-the-loop nodes | ## How It Works 1. Define goals, success criteria, and constraints 2. Generate or refine the graph with coding-agent skills 3. Run agents in local or production environments 4. Evaluate outcomes and test results 5. Evolve implementation based on measured gaps ## When to Choose Aden Choose Aden when you need: * Long-running or multi-step autonomous workflows * Strong control over quality, safety, and cost boundaries * Human approval gates for sensitive actions * A practical path from prototype to production operations ## Next Steps Define measurable success criteria, constraints, and context Understand nodes, edges, shared memory, and control flow Learn sessions, headless runtime behavior, and resilience model See how failure data drives iterative agent improvement Learn the goal, criteria, and outcome model Understand nodes, edges, and shared runtime state # Worker Agent Source: https://docs.adenhq.com/building-agent/concepts/worker-agent Runtime model for sessions, iterations, headless execution, and resilience ## What a Worker Agent Is A worker agent is a specialized runtime agent generated for a defined business process. The coding agent creates it; the worker agent executes it. ## Sessions A session is one execution against one input. * Isolated shared memory and state per session * Supports long pauses/resumes (for HITL) * Captures complete execution history for debugging ## Iterations Within a session, `event_loop` nodes iterate: 1. reason 2. call tools 3. evaluate output 4. retry or continue Iteration limits prevent runaway loops. ## Headless Execution Worker agents are designed for unattended operation: * Continuous background execution * Human intervention only at explicit checkpoints * Suitable for production process automation ## Runtime Responsibilities The runtime coordinates: * Graph execution lifecycle * LLM/tool access * Shared memory and credentials * Cost tracking and budget enforcement * Event streaming and observability * Crash recovery and checkpoint resume ## Practical Model This mirrors team operations: * define role (goal) * provide context and tools * set quality constraints * automate routine actions * escalate exceptions to humans * evolve based on outcomes ## Related Concepts * [Agent Graph](/building-agent/concepts/agent-graph) * [Evolution](/building-agent/concepts/evolution) * [Human-in-the-Loop](/building/human-in-the-loop) # Aden Credential Sync Source: https://docs.adenhq.com/building/aden-credential-sync Sync local Hive credentials with Aden-managed integrations ## Overview Aden can manage OAuth authorization and refresh centrally, while Hive keeps a local encrypted cache for runtime usage. Typical flow: 1. Hive fetches credential state from Aden when needed 2. Hive caches tokens locally for performance and resilience 3. Refresh operations are delegated to Aden 4. Optional usage reporting is sent back to Aden ## API Contract Aden credential sync expects these endpoint patterns: * `GET /v1/credentials/{integration_id}` * `POST /v1/credentials/{integration_id}/refresh` * `GET /v1/credentials` * `GET /v1/credentials/{integration_id}/validate` * `POST /v1/credentials/{integration_id}/usage` (optional) * `GET /health` Authentication headers: * `Authorization: Bearer {agent_api_key}` * `X-Tenant-ID: {tenant_id}` (optional) ## Local Integration Components Implementation in Hive lives under: * `core/framework/credentials/aden/client.py` * `core/framework/credentials/aden/provider.py` * `core/framework/credentials/aden/storage.py` These components provide: * HTTP client for Aden credential endpoints * `CredentialProvider` implementation for refresh/validate * Optional local cache + Aden fallback storage ## Integration Patterns ### Provider-only (recommended) Use encrypted local storage plus `AdenSyncProvider` for refresh and validation. ### Cached Storage Use `AdenCachedStorage` when intermittent connectivity is expected. ### Multi-tenant Create per-tenant provider/client instances with explicit tenant context and segregated credential paths. ## Error Handling Design for these cases: * Aden unavailable: use non-expired local token if present * Re-authorization required: surface reauth URL and fail explicitly * Rate-limited refresh: backoff based on retry hints ## Security Checklist * Keep API keys out of source control * Use encrypted local storage for cached tokens * Scope credentials per tenant and environment * Log metadata, not token secrets ## Related * [Credential Store](/building/credential-store) * [Quickstart](/getting-started/quickstart) # Build From Existing Agent Source: https://docs.adenhq.com/building/build-with-existing-agent Use templates and proven agent patterns to accelerate development and reach production success faster This guide shows how to start from an existing agent instead of generating one from scratch. Starting with templates or proven patterns lets you ship faster while learning Hive concepts. ## When to Use This Path Use this approach when you want to: * Reuse a proven graph pattern * Add new capabilities to an existing workflow * Create a variant for a different team, market, or policy * Fix recurring failures and ship a refined version ## Prerequisites * Existing agent under `exports/` (for example `exports/support_ticket_agent`) or `examples/` * Hive environment set up with `./quickstart.sh` * A clear change target: goals, constraints, nodes, or tools > **Tip**: Explore [use cases and templates](/getting-started/use-cases) to find a starting point that matches your workflow. ## 1. Copy the Base Agent From `exports/`: ```bash theme={null} cp -R exports/support_ticket_agent exports/support_ticket_agent_v2 ``` Or start from an example agent: ```bash theme={null} cp -R examples/support_ticket_agent exports/support_ticket_agent_v2 ``` Rename internal identifiers as needed (`name`, package/module references, and test fixtures). ## 2. Update Goal and Constraints First Open the new agent files and update: * goal statement * success criteria * hard/soft constraints * required capabilities Start with goal updates before touching node logic. This keeps implementation aligned to measurable outcomes. ## 3. Change Graph Structure Typical modifications: * Add node(s) for new tool calls or validation * Add conditional edges for fallback/retry paths * Insert `human_input` gates for sensitive actions * Split overloaded nodes into smaller steps Use these references while editing: * [Defining Goals](/building/goals) * [Node Types](/building/nodes) * [Edge Configuration](/building/edges) * [Human-in-the-Loop](/building/human-in-the-loop) ## 4. Validate the New Agent ```bash theme={null} PYTHONPATH=exports uv run python -m support_ticket_agent_v2 validate PYTHONPATH=exports uv run python -m support_ticket_agent_v2 info ``` If validation fails, resolve schema, routing, or missing capability errors before testing. ## 5. Run Regression + New Behavior Tests ```bash theme={null} PYTHONPATH=exports uv run pytest exports/support_ticket_agent_v2/tests/ -v ``` Add tests for: * unchanged baseline behavior * new branches and constraints * expected failure and escalation paths ## 6. Smoke Run ```bash theme={null} PYTHONPATH=exports uv run python -m support_ticket_agent_v2 run --input '{ "task": "example input" }' ``` Use standard runs during fast iteration. ## 7. Promote Safely Before replacing the original agent: 1. Verify success criteria are met on representative inputs. 2. Confirm hard constraints are never violated. 3. Keep the previous version available for rollback. ## Recommended Versioning Pattern Use explicit suffixes for major revisions: * `agent_name_v2` * `agent_name_v3` Avoid in-place edits to production agents without version history. ## Next Steps Strengthen regression coverage and edge-case checks Revisit runtime and evolution concepts before major refactors Prepare your refined agent for production Evolve your agent based on production feedback # Credential Store Source: https://docs.adenhq.com/building/credential-store Manage API keys and OAuth tokens for Hive agents ## Overview Hive includes a credential store for API keys, OAuth tokens, and multi-key secrets. The store is intentionally separate from tool logic: * The store keeps and resolves credential values * Tools define how those values are injected (headers, params, payloads) This separation keeps credential handling reusable and predictable. ## Core Concepts * `CredentialStore`: main API for save/load/refresh/resolve * `CredentialObject`: credential record that can contain multiple keys * `CredentialStorage`: backend interface (encrypted files, env vars, vault, composite) * `CredentialProvider`: lifecycle integration for refresh and validation ## Quick Start ```python theme={null} from framework.credentials import CredentialStore, InMemoryStorage store = CredentialStore(storage=InMemoryStorage()) store.save_api_key("brave_search", "your-api-key") api_key = store.get("brave_search") headers = store.resolve_headers({"X-Subscription-Token": "{{brave_search.api_key}}"}) ``` ## Template Resolution Use credential templates in request definitions: * `{{credential_id}}` resolves the default key * `{{credential_id.key_name}}` resolves a specific key Example: ```python theme={null} headers = store.resolve_headers({ "Authorization": "Bearer {{github_oauth.access_token}}", "X-API-Key": "{{brave_search.api_key}}", }) ``` ## Storage Backends ### Encrypted File Storage (recommended) Use encrypted local storage for production-like local environments: * Path default: `~/.hive/credentials` * Encryption key via `HIVE_CREDENTIAL_KEY` ### EnvVar Storage Use existing environment variables as read-only credentials for compatibility. ### Composite Storage Layer storages with fallback behavior, for example encrypted files as primary and env vars as fallback. ### HashiCorp Vault Use Vault storage for enterprise secret management. ## OAuth2 and Auto-Refresh Credentials can be linked to providers for refresh/validation: * Save tokens with `provider_id` * Enable `auto_refresh` * Call `store.get(...)` and let provider logic refresh when needed ## Best Practices * Use encrypted storage outside test environments * Keep provider-specific refresh logic in providers, not tool code * Never commit credential values into repositories * Add tests for token expiry and refresh paths ## Related * [Aden Credential Sync](/building/aden-credential-sync) * [Build Your First Agent](/building/first-agent) # Debugging & Logging Source: https://docs.adenhq.com/building/debugging Find and fix agent issues fast with three-level observability and AI-assisted debugging When errors or unexpected behavior happen during testing or production, you need to understand what went wrong and fix it quickly. Hive provides structured logging and AI-assisted debugging to make this as painless as possible. ## Three-Level Observability Hive uses three levels of logging to give you the right amount of detail at each stage of debugging. Start at L1 for the big picture, then drill down as needed. | Level | What It Captures | File | When to Use | | ------------------ | ------------------------------------------------------------------ | ----------------- | --------------------------------------------------------- | | **L1 (Summary)** | Run outcomes — success/failure, execution quality, attention flags | `summary.json` | Quick health check: did the agent succeed? | | **L2 (Details)** | Per-node results — retries, verdicts, latency, attention reasons | `details.jsonl` | Investigating which node failed or why routing went wrong | | **L3 (Tool Logs)** | Step-by-step execution — tool calls, LLM responses, judge feedback | `tool_logs.jsonl` | Deep debugging: exactly what the LLM saw, said, and did | Start with L1 to find the problem area, then drill into L2 and L3 only for the failing nodes. This saves time and keeps you focused. ## Debugging Workflow Look at `summary.json` for the run outcome. Did the agent succeed or fail? Are there attention flags? ```bash theme={null} hive logs --level summary ``` If the run failed, check `details.jsonl` to find which node produced the error or unexpected result. Look for retries, timeouts, and attention reasons. ```bash theme={null} hive logs --level details ``` For the failing node, examine `tool_logs.jsonl` to see the exact sequence of tool calls, LLM responses, and judge evaluations. ```bash theme={null} hive logs --level tools --node ``` Use the TUI to run the agent again with the same input and watch execution in real time. ```bash theme={null} hive tui ``` Update your node code, edge logic, or goal definition, then re-run tests to confirm the fix. ```bash theme={null} hive run --debug --input '{...}' ``` ## AI-Assisted Debugging Hive gives you an AI-assisted experience for checking logs and getting high signal-to-noise insights. Instead of reading through raw log files, the debugging tools help you: * Identify the root cause of failures from log patterns * Suggest specific fixes based on common failure modes * Highlight attention-worthy details you might otherwise miss Use the debugger skill in your coding agent: ```bash theme={null} claude> /hive-debugger ``` This opens an interactive debugging session where the coding agent reads your logs, identifies issues, and proposes targeted fixes. ## Common Issues Check L3 logs for the exact tool call and its response. Common causes: missing credentials, API rate limits, or unexpected input format. Verify your [credential store](/building/credential-store) has the right keys set up. Check L2 logs for routing decisions — the agent may be taking the wrong path through the graph. Review your [edge conditions](/building/edges) and [goal criteria](/building/goals) to make sure they match your intent. Check L2 for the retry count and L3 for why each attempt fails. The root cause is often an unreachable success condition in the node's evaluation logic. Adjust the node's constraints or add a fallback edge. Check the timeout configuration in your [HITL node](/building/human-in-the-loop). Consider adjusting the timeout duration, changing the escalation policy, or adding an auto-approve fallback for low-risk decisions. Check L1 for total token usage and L2 for per-node costs. Agents that retry frequently or use expensive models on simple tasks drive up costs. Review your model configuration and set budget limits. ## Testing vs Debugging Testing verifies your agent works correctly. Debugging investigates why it doesn't. Use them together: * **Before deployment:** Write [tests](/building/testing) for your goal criteria and constraints * **After a failure:** Use the debugging workflow above to diagnose and fix * **After a fix:** Add a regression test so the same failure doesn't happen again ## Next Steps Set up goal-based testing to catch issues before they reach production. Deploy your debugged agent to production with confidence. # Deployment Source: https://docs.adenhq.com/building/deployment Deploy agents to production — locally with Docker, on Aden Cloud for zero-ops, or as fully autonomous systems Once your agent passes testing and you're confident in its behavior, it's time to ship it. Hive supports three deployment models depending on your needs. ## Deployment Models Full control. Run agents on your own infrastructure with Docker. Zero-ops. Managed deployment with built-in logging, scaling, and credential management. Self-running. Agents that operate continuously with event-driven triggers and self-recovery. ## Local Deployment By default, Hive supports deployment through Docker. This gives you full control over your runtime environment, networking, and credentials. Validate your agent before deploying. This checks structure, credentials, and dependencies. ```bash theme={null} hive validate ``` ```bash theme={null} hive deploy local ``` This builds a container with your agent, its dependencies, and the Hive runtime. Your agent uses local credentials for APIs and services. For OAuth-based integrations, Aden Cloud handles token refresh automatically. Check that the agent is running and accessible: ```bash theme={null} hive status ``` Prefer isolated environments (container, VM, or dedicated host). Keep credentials in secure secret stores. Use environment-scoped configs for staging vs. production. ## Cloud Deployment If you want managed infrastructure with easier credential management and built-in observability, Aden Cloud is the simpler path. You get secure defaults, scaling, and logging out of the box — at the cost of less low-level control. **What you get with Aden Cloud:** * Managed compute and scaling * Built-in credential sync and OAuth refresh * Real-time logging and monitoring dashboard * Automatic restarts and failure recovery * Cost tracking and budget enforcement See [Create an Account](/getting-started/create-account) to get started with Aden Cloud, or [Aden Credential Sync](/building/aden-credential-sync) for how cloud credentials work. ## Autonomous Agent Deployment For agents that need to run continuously without human intervention, Hive provides built-in support for autonomous operation: * **Memory sustainability** — Decide what memory to keep and what to discard across sessions, so your agent doesn't grow unbounded or forget critical context * **Event source management** — Trigger agent runs from external events like incoming emails, webhooks, or scheduled cron jobs * **Recoverability** — Automatically recover from crashes and resume from the last checkpoint * **Repeatability** — Ensure consistent behavior across identical inputs * **Volume handling** — Support batch operations when you need to process many items at once ## Deployment Strategy Interactive and autonomous modes look different from the outside, but the core remains the same. Your deployment strategy should be consistent across both: Run your agent with `hive tui` to validate behavior with real inputs. Set up cron-based or event-triggered runs. Monitor logs and costs. Remove the human-in-the-loop gates for low-risk decisions. Keep alerts for failures and escalations. ## Runtime Guardrails Hive provides built-in safety mechanisms to keep your agents within bounds in production: * **Cost limits** — Set maximum spend per run, per day, or per month * **Timeout policies** — Prevent runaway execution with configurable timeouts * **Model degradation** — Automatically fall back to cheaper models when budget runs low * **Human-in-the-loop gates** — Require human approval for high-impact actions * **Escalation policies** — Route failures to the right person instead of silently breaking ## Developer Trust To deploy agents for production use with confidence, Hive provides: * **Transparency** — Full visibility into what the agent did and why through three-level [logging](/building/debugging) * **Control** — Configurable guardrails, intervention points, and approval flows * **Reliability** — Self-healing mechanisms and failure recovery built into the runtime ## Next Steps Improve your deployed agent based on real-world performance. Diagnose and fix production issues with three-level observability. # Edge Configuration Source: https://docs.adenhq.com/building/edges Connect nodes with success, failure, and conditional edges ## Overview Edges define how execution flows between nodes in your agent graph. Unlike traditional frameworks that hardcode workflows, Aden's edges are dynamically generated based on your goals. ## Edge Types | Type | Trigger | Use Case | | ------------- | --------------------------- | ----------------------- | | `on_success` | Node completes successfully | Normal flow progression | | `on_failure` | Node throws an error | Error handling, retries | | `conditional` | Output matches a condition | Branching logic | ## Basic Syntax ```json theme={null} { "edges": [ {"from": "node_a", "to": "node_b", "type": "on_success"}, {"from": "node_a", "to": "error_handler", "type": "on_failure"}, {"from": "router", "to": "path_a", "when": "category == 'A'"}, {"from": "router", "to": "path_b", "when": "category == 'B'"} ] } ``` ## Success Edges Execute the next node when the current node completes without errors. ```json theme={null} { "from": "classify_request", "to": "generate_response", "type": "on_success" } ``` ### Passing Data Output from the source node becomes input for the target: ```mermaid theme={null} flowchart LR A["classify_request
output: {category: 'billing'}"] -->|on_success| B["generate_response
input: {category: 'billing'}"] ``` ## Failure Edges Execute when a node throws an error or times out. ```json theme={null} { "from": "api_call", "to": "retry_handler", "type": "on_failure" } ``` ### Error Context Failed nodes pass error information: ```python theme={null} { "error": { "type": "TimeoutError", "message": "Request timed out after 30s", "node_id": "api_call", "attempt": 1 }, "original_input": {...} } ``` ### Retry Pattern ```json theme={null} { "nodes": [ { "id": "api_call", "type": "function", "handler": "tools.external_api" }, { "id": "retry_handler", "type": "function", "handler": "tools.retry_with_backoff", "config": {"max_attempts": 3, "backoff": "exponential"} } ], "edges": [ {"from": "api_call", "to": "next_step", "type": "on_success"}, {"from": "api_call", "to": "retry_handler", "type": "on_failure"}, {"from": "retry_handler", "to": "api_call", "type": "on_success"}, {"from": "retry_handler", "to": "fallback", "type": "on_failure"} ] } ``` ## Conditional Edges Route based on output values using expressions. ```json theme={null} { "from": "sentiment_analysis", "to": "escalate", "when": "sentiment == 'negative' && confidence > 0.8" } ``` ### Expression Syntax | Operator | Description | Example | | -------------------- | ----------- | ---------------------------------- | | `==` | Equals | `status == 'approved'` | | `NOT_EQUAL` | Not equals | `type NOT_EQUAL 'spam'` | | `>`, `<`, `>=`, `<=` | Comparison | `score >= 0.7` | | `&&` | Logical AND | `type == 'urgent' && priority > 5` | | `\|\|` | Logical OR | `status == 'error' OR retries > 3` | | `in` | Contains | `category in ['billing', 'sales']` | ### Accessing Nested Values ```json theme={null} { "when": "response.metadata.confidence > 0.9" } ``` ## Multiple Outgoing Edges A node can have multiple outgoing edges: ```json theme={null} { "edges": [ {"from": "analyze", "to": "approve", "when": "risk == 'low'"}, {"from": "analyze", "to": "review", "when": "risk == 'medium'"}, {"from": "analyze", "to": "reject", "when": "risk == 'high'"}, {"from": "analyze", "to": "error_handler", "type": "on_failure"} ] } ``` ### Default Path Use a default edge when no conditions match: ```json theme={null} { "edges": [ {"from": "router", "to": "path_a", "when": "type == 'A'"}, {"from": "router", "to": "path_b", "when": "type == 'B'"}, {"from": "router", "to": "default_handler", "default": true} ] } ``` ## Parallel Execution Execute multiple nodes in parallel by having multiple success edges: ```json theme={null} { "edges": [ {"from": "start", "to": "task_a", "type": "on_success", "parallel": true}, {"from": "start", "to": "task_b", "type": "on_success", "parallel": true}, {"from": "start", "to": "task_c", "type": "on_success", "parallel": true}, {"from": ["task_a", "task_b", "task_c"], "to": "aggregate", "type": "on_all_success"} ] } ``` ### Join Strategies | Strategy | Description | | ----------------- | --------------------------------------------- | | `on_all_success` | Wait for all parallel nodes to succeed | | `on_any_success` | Continue when first node succeeds | | `on_all_complete` | Wait for all to complete (success or failure) | ## Edge Transformation Transform data between nodes: ```json theme={null} { "from": "extract_entities", "to": "validate_entities", "type": "on_success", "transform": { "entities": "$.output.entities", "source_document": "$.input.document_id" } } ``` ## Visualization Your agent graph can be visualized: ```mermaid theme={null} flowchart TD START["Start"] --> CLASSIFY["Classify Request"] CLASSIFY -->|on_success| ROUTER["Priority Router"] CLASSIFY -->|on_failure| ERROR["Error Handler"] ROUTER -->|urgent| ESCALATE["Escalate to Human"] ROUTER -->|normal| PROCESS["Auto Process"] ROUTER -->|low| QUEUE["Add to Queue"] PROCESS --> RESPOND["Send Response"] ESCALATE --> RESPOND QUEUE --> END["End"] RESPOND --> END ERROR --> END ``` ## Next Steps Add human intervention points to your graph Test your agent's edge behavior # Build Your First Agent Source: https://docs.adenhq.com/building/first-agent Create your first goal-driven AI agent in minutes and start your path to developer success > **First Success Path**: This guide walks you through the first step of Aden Hive's developer success journey: **create** → debug → maintain → deploy → iterate. By the end, you'll have a working agent ready to test and refine. ## Prerequisites Before building your first agent, ensure you have: * [Python 3.11+](https://www.python.org/downloads/) installed * [Claude Code](https://claude.com/claude-code), Cursor, or OpenAI Codex CLI * At least one LLM API key configured ## 1. Install Hive ```bash theme={null} git clone https://github.com/adenhq/hive.git cd hive ./quickstart.sh ``` This sets up: * `framework` runtime package * `aden_tools` MCP tools package * Workspace dependencies for local development ## 2. Create an Agent Open Claude Code in the repo and run: ```bash theme={null} claude> /hive ``` The guided flow will help you: 1. Define the goal and success criteria 2. Pick nodes and execution strategy 3. Add constraints and human checkpoints 4. Export the generated agent package under `exports/` ## 3. Validate and Test Run the testing skill: ```bash theme={null} claude> /hive-test ``` Or run CLI checks manually: ```bash theme={null} PYTHONPATH=exports uv run python -m faq_agent validate PYTHONPATH=exports uv run python -m faq_agent info ``` ## 4. Run the Agent ```bash theme={null} PYTHONPATH=exports uv run python -m faq_agent run --input '{ "question": "How do I reset my password?" }' ``` ## Project Structure Agents created through Hive are exported to `exports/`: ```text theme={null} hive/ ├── core/ # Framework runtime ├── tools/ # MCP tools package ├── exports/ # Generated and custom agents │ └── your_agent/ │ ├── __init__.py │ ├── agent.json │ ├── tools.py │ └── tests/ └── quickstart.sh ``` ## Next Steps Define measurable outcomes and constraints Learn when to use LLM, router, function, and human nodes Configure success, failure, and conditional routing Build goal-based test coverage for your agent Diagnose and fix issues before production Move your agent to production safely Evolve your agent based on production feedback # Defining Goals Source: https://docs.adenhq.com/building/goals Define what your agent should achieve with success criteria and constraints Goals are the foundation of goal-driven agents in Aden. They define **WHAT** your agent should achieve, not **HOW**. For the conceptual foundation behind goals and success criteria, see [Outcome-Driven Development](/building-agent/concepts/outcome-driven-development). ## What is a Goal? A Goal contains: * **Success Criteria** - Measurable conditions that define success * **Constraints** - Boundaries the agent must respect * **Context** - Additional information for decision-making ```python theme={null} from framework.graph.goal import Goal, SuccessCriterion, Constraint goal = Goal( id="my-goal", name="My Agent Goal", description="What this agent should accomplish", success_criteria=[...], constraints=[...], ) ``` ## Defining Success Criteria Success criteria are **measurable conditions** that determine if your agent succeeded. ### Structure ```python theme={null} SuccessCriterion( id="unique-id", description="Human-readable description", metric="how to measure", target="target value", weight=1.0, # Relative importance (0-1) ) ``` ### Metric Types | Metric | Use Case | Example Target | | ----------------- | ------------------------------------ | ------------------ | | `output_contains` | Check if output has specific content | `"success"` | | `output_equals` | Exact match | `"expected_value"` | | `llm_judge` | LLM evaluates quality | `">= 0.8"` | | `custom` | Custom evaluation function | varies | ### Example ```python theme={null} success_criteria = [ SuccessCriterion( id="completeness", description="Response covers all requested topics", metric="llm_judge", target=">= 0.9", weight=0.5, ), SuccessCriterion( id="accuracy", description="Information is factually correct", metric="llm_judge", target=">= 0.95", weight=0.5, ), ] ``` ## Defining Constraints Constraints are **boundaries** your agent must respect during execution. ### Constraint Types | Type | Meaning | Effect | | ------ | ---------------------- | ------------------- | | `hard` | Must not violate | Violation = failure | | `soft` | Should avoid violating | Violation = warning | ### Categories * `time` - Execution time limits * `cost` - Token/API cost limits * `safety` - Safety requirements * `scope` - What the agent should/shouldn't do * `quality` - Quality requirements ### Example ```python theme={null} constraints = [ Constraint( id="no-external-apis", description="Do not call external APIs without user approval", constraint_type="hard", category="safety", ), Constraint( id="response-length", description="Keep responses under 500 words", constraint_type="soft", category="quality", ), ] ``` ## Complete Example Here's a complete goal for a research agent: ```python theme={null} from framework.graph.goal import Goal, SuccessCriterion, Constraint research_goal = Goal( id="research-agent-goal", name="Technical Research Agent", description="Research technical topics and provide comprehensive summaries", success_criteria=[ SuccessCriterion( id="topic-coverage", description="Covers all major aspects of the topic", metric="llm_judge", target=">= 0.9", weight=0.4, ), SuccessCriterion( id="source-quality", description="Uses credible sources", metric="llm_judge", target=">= 0.8", weight=0.3, ), SuccessCriterion( id="clarity", description="Output is clear and well-structured", metric="llm_judge", target=">= 0.85", weight=0.3, ), ], constraints=[ Constraint( id="verify-sources", description="All information must be from verifiable sources", constraint_type="hard", category="quality", ), Constraint( id="no-speculation", description="Do not include unverified speculation", constraint_type="hard", category="safety", ), Constraint( id="time-limit", description="Complete research within 5 minutes", constraint_type="soft", category="time", ), ], required_capabilities=["web_search", "llm"], context={ "domain": "technology", "audience": "developers", }, ) ``` ## Best Practices * Use **specific, measurable** success criteria * Include **3-5 success criteria** with different weights * Define **hard constraints** for critical requirements * Add **context** to help the agent make better decisions * Use vague criteria like "do a good job" * Skip constraints entirely * Set all weights to 1.0 (use relative importance) * Forget to specify required capabilities ## Next Steps Learn about LLM, Router, Function, and Human nodes Configure success, failure, and conditional edges # Human-in-the-Loop Source: https://docs.adenhq.com/building/human-in-the-loop Add human intervention points for approvals, escalations, and quality control ## Overview Human-in-the-loop (HITL) nodes pause agent execution to collect human input. This enables: * **Approvals** - High-stakes decisions requiring human sign-off * **Escalation** - Complex cases beyond agent capabilities * **Quality Control** - Spot-checking agent outputs * **Training Data** - Collecting human feedback for improvement ## Basic Configuration ```json theme={null} { "id": "approval_gate", "type": "human", "prompt": "Review and approve this action: {{action_description}}", "options": ["approve", "reject", "modify"], "timeout": "24h", "escalation": "auto_reject" } ``` ## Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------------ | | `prompt` | string | Yes | Instructions/question for the human | | `options` | array | No | Predefined response choices | | `timeout` | string | No | Time limit (e.g., "1h", "24h", "7d") | | `escalation` | string | No | Timeout action: `auto_approve`, `auto_reject`, `escalate`, `retry` | | `assignee` | string | No | User, role, or team to notify | | `priority` | string | No | `low`, `medium`, `high`, `urgent` | | `context` | object | No | Additional context to display | ## Approval Patterns ### Simple Approval Binary approve/reject for high-stakes decisions: ```json theme={null} { "id": "manager_approval", "type": "human", "prompt": "Approve refund of ${{amount}} for customer {{customer_name}}?", "options": ["approve", "reject"], "timeout": "4h", "escalation": "escalate", "assignee": "role:manager" } ``` ### Multi-Level Approval Chain multiple approval steps: ```mermaid theme={null} flowchart LR REQUEST["Request"] --> L1["L1 Approval"] L1 -->|approve| L2["L2 Approval"] L1 -->|reject| REJECT["Rejected"] L2 -->|approve| EXECUTE["Execute"] L2 -->|reject| REJECT ``` ```json theme={null} { "nodes": [ { "id": "l1_approval", "type": "human", "prompt": "L1 Review: {{request}}", "assignee": "role:l1_approver", "timeout": "8h" }, { "id": "l2_approval", "type": "human", "prompt": "L2 Final Approval: {{request}}", "assignee": "role:l2_approver", "timeout": "24h" } ] } ``` ## Escalation Patterns ### Confidence-Based Escalation Escalate when agent confidence is low: ```json theme={null} { "nodes": [ { "id": "generate_response", "type": "llm", "output_schema": { "properties": { "response": {"type": "string"}, "confidence": {"type": "number"} } } }, { "id": "human_review", "type": "human", "prompt": "Agent response (confidence: {{confidence}}):\n\n{{response}}\n\nApprove or edit?", "options": ["approve", "edit"] } ], "edges": [ {"from": "generate_response", "to": "send_response", "when": "confidence >= 0.8"}, {"from": "generate_response", "to": "human_review", "when": "confidence < 0.8"} ] } ``` ### Exception-Based Escalation Escalate specific scenarios: ```json theme={null} { "edges": [ {"from": "process_request", "to": "human_review", "when": "amount > 10000"}, {"from": "process_request", "to": "human_review", "when": "customer.is_vip == true"}, {"from": "process_request", "to": "human_review", "when": "risk_score > 0.7"} ] } ``` ## Timeout Handling Configure what happens when humans don't respond: | Escalation Action | Behavior | | ----------------- | ---------------------------------- | | `auto_approve` | Automatically approve and continue | | `auto_reject` | Automatically reject and stop | | `escalate` | Notify next level / manager | | `retry` | Resend notification | | `queue` | Move to low-priority queue | ### Escalation Chain ```json theme={null} { "id": "urgent_approval", "type": "human", "prompt": "Urgent: Approve {{action}}", "timeout": "1h", "escalation": { "action": "escalate", "to": "role:senior_manager", "timeout": "4h", "final_action": "auto_reject" } } ``` ## Context and Display Provide rich context for human reviewers: ```json theme={null} { "id": "fraud_review", "type": "human", "prompt": "Review potential fraud case", "context": { "transaction": { "amount": "{{amount}}", "merchant": "{{merchant}}", "location": "{{location}}" }, "risk_factors": "{{risk_factors}}", "customer_history": "{{customer_history}}", "similar_cases": "{{similar_cases}}" }, "display": { "layout": "side-by-side", "highlight": ["risk_factors"] } } ``` ## Response Handling ### Structured Responses Collect structured data from humans: ```json theme={null} { "id": "quality_review", "type": "human", "prompt": "Rate this response", "response_schema": { "type": "object", "properties": { "approved": {"type": "boolean"}, "quality_score": {"type": "integer", "minimum": 1, "maximum": 5}, "feedback": {"type": "string"}, "corrections": {"type": "string"} }, "required": ["approved", "quality_score"] } } ``` ### Response-Based Routing Route based on human response: ```json theme={null} { "edges": [ {"from": "human_review", "to": "execute", "when": "response.approved == true"}, {"from": "human_review", "to": "revise", "when": "response.approved == false && response.corrections"}, {"from": "human_review", "to": "reject", "when": "response.approved == false && response.corrections == null"} ] } ``` ## Assignment Strategies ### Role-Based Assignment ```json theme={null} { "assignee": "role:customer_support" } ``` ### Round-Robin ```json theme={null} { "assignee": { "strategy": "round_robin", "pool": ["user:alice", "user:bob", "user:charlie"] } } ``` ### Load-Based ```json theme={null} { "assignee": { "strategy": "least_busy", "pool": "team:support" } } ``` ## Best Practices Provide all context needed for the human to make a decision Set timeouts based on urgency and expected response time Always have a fallback when humans don't respond Use human responses to improve agent performance over time ## Next Steps Test HITL workflows with mock responses Learn about other node types # Iteration Source: https://docs.adenhq.com/building/iteration Evolve your agents from MVP to production-grade — expand use cases, improve reliability, and let the evolution loop do the work After your agent runs successfully for the first time, the real work begins: making it better. Hive is designed for continuous iteration, from expanding what your agent can do to letting the framework automatically improve it. ## Two Modes of Iteration ### Building Iteration — Expanding Your Agent After your MVP agent or sample agent runs, you'll want to expand its capabilities. This is like debugging, but forward-looking: instead of fixing what's broken, you're adding what's missing. Common iteration patterns: * **Add new integrations** — Connect your agent to additional tools and APIs as your workflow expands * **Handle more edge cases** — Add nodes and edges that cover scenarios your initial agent didn't address * **Improve prompts** — Refine node prompts based on real-world output quality * **Add human-in-the-loop gates** — Insert approval steps for high-risk actions you initially automated * **Tighten constraints** — Add cost limits, timeout policies, or quality thresholds Use `hive tui` to test each iteration interactively before deploying. Run the same inputs through your updated agent and compare outputs. ### Production Iteration — Evolution and Adaptation Once your agent is deployed, your taste and judgment still drive the direction — but AI becomes a significant force multiplier for rapidly iterating and solving problems. With Aden Cloud, production evolution can be fully automatic. The system runs continuous evaluation cycles: Your agent runs against real-world inputs in production. Outcomes are measured against your goal's success criteria and constraints. The framework identifies failure patterns and areas for improvement. The coding agent proposes changes to prompts, graph structure, edges, or tools. Updated agents are deployed and the cycle continues. ## Version Control Iteration doesn't always improve everything. Sometimes a change helps one use case but hurts another. Hive includes version control so you can always go back. ```bash theme={null} # Restore to a previous version hive git restore ``` Think of it like git for your agents — every meaningful change is tracked, and you can revert when needed. ## Agent Personality Not everything should change with iteration. Your agent has a personality — the tone, values, and goals that define who it is. Success isn't about having your agent constantly changing. It's about knowing that **your goal and personality stay fixed while the agent adapts to solve problems**. When you set up your agent's goal, the core identity persists across evolution cycles. The framework changes *how* the agent achieves the goal, not *what* the goal is. ## Memory Management As your agent iterates and runs more sessions, memory management becomes important. Hive nodes have built-in mechanisms for: * **Node memory** — Each node maintains its own working memory within a session * **Memory passing** — Structured data flows between nodes through edges * **Cross-session memory** — Persistent memory that survives between runs using memory tools * **Memory compaction** — Automatic cleanup to prevent unbounded memory growth For custom memory logic or cross-session persistence, use the memory tools provided by the SDK. ## The Iteration Lifecycle Over time, your agent should progress through these stages: | Stage | What You Do | What Hive Does | | ----------------- | ------------------------------- | -------------------------------------- | | **MVP** | Build and test with templates | Generate graph, validate structure | | **First Success** | Deploy and monitor | Run, log, and surface attention flags | | **Expansion** | Add integrations and edge cases | Track what works and what fails | | **Maturity** | Set it and monitor | Evolve automatically based on outcomes | Everything before "First Success" should run as smoothly as possible — this is non-negotiable. The docs, templates, and tools are all designed to get you there fast. ## Contributing Your Improvements If you've built something useful or found a better way to solve a common problem, share it with the community: * **Open an issue** on [GitHub](https://github.com/adenhq/hive/issues) if you encounter limitations * **Share your agent** in [Discord](https://discord.com/invite/MXE49hrKDk) for feedback * **Contribute a template** if your agent solves a common business process — see [CONTRIBUTING.md](https://github.com/adenhq/hive/blob/main/CONTRIBUTING.md) ## Next Steps Understand the theory behind Hive's adaptive evolution loop. When iteration reveals new issues, use three-level observability to diagnose them. # Node Types Source: https://docs.adenhq.com/building/nodes LLM, Router, Function, and Human nodes for building agent graphs ## Overview Nodes are the building blocks of Aden agents. Each node type serves a specific purpose in the agent graph. | Node Type | Purpose | When to Use | | ------------ | ------------------------ | ---------------------------------------------- | | **LLM** | Language model inference | Text generation, classification, extraction | | **Router** | Control flow decisions | Branching logic, conditional paths | | **Function** | Custom code execution | API calls, data transformation, business logic | | **Human** | Human intervention | Approvals, complex decisions, quality checks | ## LLM Node Executes a language model call with structured inputs and outputs. ### Configuration ```json theme={null} { "id": "analyze_sentiment", "type": "llm", "model": "claude-sonnet-4-5-20250929", "prompt": "Analyze the sentiment of this text: {{text}}", "system": "You are a sentiment analysis expert.", "output_schema": { "type": "object", "properties": { "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]}, "confidence": {"type": "number", "minimum": 0, "maximum": 1} }, "required": ["sentiment", "confidence"] }, "temperature": 0.3, "max_tokens": 500 } ``` ### Parameters | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------ | | `model` | string | Yes | LLM model identifier | | `prompt` | string | Yes | Prompt template with `{{variable}}` placeholders | | `system` | string | No | System message for the LLM | | `output_schema` | object | No | JSON schema for structured output | | `temperature` | number | No | Sampling temperature (0-2) | | `max_tokens` | number | No | Maximum tokens to generate | | `tools` | array | No | Tools the LLM can call | ### Tool Calling LLM nodes can call tools/functions: ```json theme={null} { "id": "research_agent", "type": "llm", "model": "claude-sonnet-4-5-20250929", "prompt": "Research this topic: {{topic}}", "tools": [ {"name": "web_search", "description": "Search the web"}, {"name": "read_file", "description": "Read a file from disk"} ] } ``` ## Router Node Routes execution flow based on conditions or LLM decisions. ### Conditional Routing Route based on output values from previous nodes: ```json theme={null} { "id": "priority_router", "type": "router", "conditions": [ {"path": "urgent_handler", "when": "priority == 'high'"}, {"path": "normal_handler", "when": "priority == 'medium'"}, {"path": "low_priority_queue", "when": "priority == 'low'"}, {"path": "default_handler", "default": true} ] } ``` ### LLM-Decided Routing Let the LLM choose the path: ```json theme={null} { "id": "intent_router", "type": "router", "strategy": "llm", "model": "claude-haiku-4-5-20251001", "prompt": "Which handler should process this request? {{request}}", "paths": [ {"name": "billing", "description": "Billing and payment questions"}, {"name": "technical", "description": "Technical support issues"}, {"name": "sales", "description": "Sales and pricing inquiries"} ] } ``` ### Weighted Routing Probabilistic routing for A/B testing: ```json theme={null} { "id": "ab_router", "type": "router", "strategy": "weighted", "weights": [ {"path": "variant_a", "weight": 0.8}, {"path": "variant_b", "weight": 0.2} ] } ``` ## Function Node Executes custom Python code. ### Basic Function ```json theme={null} { "id": "send_email", "type": "function", "handler": "tools.email.send", "inputs": ["recipient", "subject", "body"], "timeout": "30s" } ``` ### Implementation ```python theme={null} # tools/email.py async def send(ctx, recipient: str, subject: str, body: str): """Send an email via the configured SMTP server.""" smtp = ctx.tools.get("smtp_client") result = await smtp.send( to=recipient, subject=subject, body=body ) return {"sent": True, "message_id": result.id} ``` ### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------- | | `handler` | string | Yes | Python function path | | `inputs` | array | No | Required input fields | | `timeout` | string | No | Execution timeout | | `retry` | object | No | Retry configuration | ## Human Node Pauses execution for human input. ### Basic Configuration ```json theme={null} { "id": "manager_approval", "type": "human", "prompt": "Approve refund of ${{amount}} for {{customer}}?", "options": ["approve", "reject", "escalate"], "timeout": "24h", "escalation": "auto_reject" } ``` ### Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------ | | `prompt` | string | Yes | Question/instructions for the human | | `options` | array | No | Predefined response options | | `timeout` | string | No | Time limit for human response | | `escalation` | string | No | Action on timeout: `auto_approve`, `auto_reject`, `escalate` | | `assignee` | string | No | Specific user/role to notify | See [Human-in-the-Loop](/building/human-in-the-loop) for advanced patterns. ## Node Context All nodes receive a context object: ```python theme={null} class NodeContext: # Input from previous node input: dict # Shared memory store memory: MemoryStore # LLM client llm: LLMClient # Tool registry tools: ToolRegistry # Run metadata metadata: RunMetadata ``` ### Using Context in Functions ```python theme={null} async def my_function(ctx): # Read from memory user_data = await ctx.memory.get("user_profile") # Call LLM response = await ctx.llm.complete( model="claude-haiku-4-5-20251001", prompt="Summarize: " + ctx.input["text"] ) # Use tools result = await ctx.tools.call("web_search", query="...") # Write to memory await ctx.memory.set("summary", response.text) return {"summary": response.text} ``` ## Next Steps Connect nodes with success, failure, and conditional edges Configure human intervention patterns # Testing Agents Source: https://docs.adenhq.com/building/testing Validate agent behavior with goal-based and regression testing to build confidence and ensure production readiness ## Overview Testing is the foundation of developer confidence. In Hive, comprehensive testing confirms three critical things: * The agent meets success criteria defined by the goal * Constraints are respected under normal and edge inputs * Failure and escalation paths behave as expected ## Recommended Workflow 1. Generate or refine tests with the coding agent: ```bash theme={null} claude> /hive-test ``` 2. Run focused suites while iterating: ```bash theme={null} PYTHONPATH=exports uv run pytest exports/your_agent/tests/ -v ``` 3. Run goal-based checks before merge: ```bash theme={null} uv run hive test-run exports/your_agent --goal your_goal_id ``` ## Common Commands ### Run all tests for an agent ```bash theme={null} PYTHONPATH=exports uv run pytest exports/your_agent/tests/ -v ``` ### Run a single test ```bash theme={null} PYTHONPATH=exports uv run pytest \ exports/your_agent/tests/test_agent.py::test_happy_path -v ``` ### Run goal-aware CLI test runner ```bash theme={null} uv run hive test-run exports/your_agent --goal your_goal_id ``` ### List generated tests ```bash theme={null} uv run hive test-list exports/your_agent ``` ### Debug a failing test ```bash theme={null} uv run hive test-debug exports/your_agent test_constraint_budget_limit ``` ## What to Test ### Goal Completion * Primary success criteria are satisfied * Weighted criteria do not regress across releases ### Constraints * Hard constraints always fail safely * Soft constraints emit warnings or fallback behavior ### Routing and Retries * Conditional edges take the correct branch * Retry loops terminate and do not stall the graph ### Human-in-the-Loop * Pause/resume paths work * Timeout and escalation behavior match requirements ## CI Example ```yaml theme={null} name: Agent Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup run: ./quickstart.sh - name: Pytest run: PYTHONPATH=exports uv run pytest exports/*/tests/ -v --tb=short ``` ## Best Practices * Keep unit-level tests deterministic with mocked tool responses * Add regression tests for every production failure you fix * Treat constraints as mandatory API contracts, not optional hints * Track test coverage across success, failure, retry, and HITL branches > **Testing and Debugging**: Testing catches issues before production. Once your agent is live, [debugging](/building/debugging) tools help you diagnose and fix issues based on real-world behavior. ## Next Steps Create and export a new agent package Add supervised decision points to sensitive actions Diagnose and fix issues discovered in testing or production Deploy your tested agent to production # Create an Account Source: https://docs.adenhq.com/getting-started/create-account Get started with Aden by creating your account and generating your API key. ## Create an Account To start using Aden, you'll need to create an account on our platform. 1. Go to the registration URL ([https://arp.adenhq.com/register-agent-control](https://arp.adenhq.com/register-agent-control)). 2. Sign up using your work email or Google account. 3. Follow the onboarding steps to set up your workspace. Once you've created your account, you'll land on the main dashboard where you can manage your integration. ## Generate Developer Token To authenticate your requests to the Aden API, you need a developer token (API Key). 1. Log in to your [Aden Dashboard](https://app.adenhq.com). 2. Go to **Settings** > **API Keys**. 3. Click on **Generate New Key**. 4. Give your key a descriptive name (e.g., "Development", "Production"). 5. Click **Create**. 6. **Important:** Copy the key immediately and store it securely. You won't be able to see it again. Treat your API key like a password. Do not share it or commit it to version control systems like GitHub. Use environment variables to manage your keys securely. # Quickstart Source: https://docs.adenhq.com/getting-started/quickstart Install Hive and reach your first success — a running, goal-driven agent — in under 10 minutes By the end of this guide, you'll have Hive installed and your first agent running. That's your **First Success** — and everything from here should be smooth. ## Prerequisites Python 3.11, 3.12, or 3.13. Check with `python --version`. An API key for Anthropic, OpenAI, Gemini, or another LiteLLM-supported provider. **Windows users:** Use WSL (Windows Subsystem for Linux) or Git Bash. Some automation scripts may not run correctly in standard Command Prompt or PowerShell. ## Step 1: Clone and Install ```bash theme={null} git clone https://github.com/adenhq/hive.git cd hive ./quickstart.sh ``` The setup wizard handles everything: * Checks Python and installs `uv` if needed * Installs workspace packages (`framework` and `aden_tools`) * Installs Playwright browser dependencies when available * Verifies imports and local environment health * Guides LLM provider configuration ```bash theme={null} # Install dependencies uv sync # Verify everything works uv run python -c "import framework; print('framework OK')" uv run python -c "import aden_tools; print('aden_tools OK')" uv run python -c "import litellm; print('litellm OK')" ``` ## Step 2: Set Up Your LLM Provider Export at least one provider API key: ```bash theme={null} export ANTHROPIC_API_KEY="sk-ant-..." ``` The quickstart script can detect existing keys in your environment and generate a default Hive provider configuration automatically. ## Step 3: Build Your First Agent Use your coding agent to create an agent through a guided conversation: ```bash theme={null} claude> /hive ``` This walks you through defining your goal, generating the agent graph, and setting up the required nodes and edges. No manual wiring needed. ## Step 4: Test It Run your agent interactively to see it work: ```bash theme={null} # Interactive dashboard hive tui # Or run directly with input hive run exports/your_agent_name --input '{"task": "Your input here"}' ``` **First Success!** If your agent ran and produced output, you've reached the milestone. Everything from here — debugging, deployment, iteration — builds on this foundation. ## What Just Happened When you built your agent, Hive: 1. **Parsed your goal** into structured success criteria and constraints 2. **Generated a node graph** with the right nodes, edges, and connection code 3. **Wrapped each node** with the SDK — giving it memory, LLM access, tools, and observability 4. **Ran the graph** against your input, evaluating outcomes at each step ## Alternative: Start From a Template If you'd rather start from something that already works and customize it: ```bash theme={null} # Browse available agents hive tui # Or copy an existing template and make it yours ``` See [Build From Existing Agent](/building/build-with-existing-agent) for the full workflow. ## Next Steps Detailed guide to creating custom goal-driven agents. Browse ready-made agents you can deploy or customize. Understand goals, graphs, and the runtime model. Add goal-based tests before deploying to production. # Self-Hosting Source: https://docs.adenhq.com/getting-started/self-hosting Run Aden Hive on your own infrastructure Self-hosting guidance is in active iteration. Use this page as an alpha baseline and validate against the latest `hive/README.md` before production rollout. ## Overview Self-hosting Hive gives you control over runtime environment, networking, and credentials. ## Baseline Setup 1. Clone and prepare the repository: ```bash theme={null} git clone https://github.com/adenhq/hive.git cd hive ./quickstart.sh ``` 2. Configure provider credentials (for example): ```bash theme={null} export ANTHROPIC_API_KEY="sk-ant-..." ``` 3. Run agents from your own infrastructure: ```bash theme={null} PYTHONPATH=exports uv run python -m your_agent_name run --input '{...}' ``` ## Deployment Notes * Prefer isolated environments (container, VM, or dedicated host) * Keep credential material in secure secret stores * Use environment-scoped configs for staging vs production * Add observability and alerting before enabling autonomous workflows > **Complete Deployment Story**: Self-hosting covers the infrastructure setup. For comprehensive guidance on deployment strategies, monitoring, and safe rollout procedures, see the [deployment guide](/building/deployment). ## Troubleshooting ### Dependency setup issues ```bash theme={null} uv sync uv run python -c "import framework, aden_tools; print('ok')" ``` ### Runtime import issues Run commands from the `hive/` project root and ensure `PYTHONPATH=exports` is set. ## Need Help? Get help with production deployment and architecture decisions. ## Next Steps Set up local development and first execution Create and test your first goal-driven agent Move your agent from development to production safely Track agent health and performance in production # Use Cases & Templates Source: https://docs.adenhq.com/getting-started/use-cases Ready-to-run agent templates for real business processes — start from a template, customize it, and deploy Hive ships with agent templates you can run immediately or use as a starting point for your own agents. Each template is a complete, working agent that covers a real business process. Every template can be run as-is with `hive tui` or customized to fit your needs. See [Build From Existing Agent](/building/build-with-existing-agent) for the customization workflow. ## Starter Templates These are the best starting points — simple enough to understand in minutes, useful enough to deploy immediately. Automatically categorize, label, and route incoming GitHub issues by severity and type. Curate a daily digest of the most relevant tech and AI news for your team. Generate structured research reports on any topic with source citations. Summarize daily activity and extract action items from your team communications. Automatically respond to common questions in your Discord server. Daily summary of stock movements, market trends, and financial news. Handle routine WhatsApp messages with intelligent automated replies. Track conversations and send timely follow-ups when responses go quiet. Find optimal meeting times across multiple participants and time zones. ## Sales & Marketing Marketing is often the most time-consuming distraction for a CEO. You provide the vision; the agents provide the volume. Schedule posts, reply to comments, and monitor trends across platforms. Keeps your presence consistent without daily manual effort. Personalized outreach triggered by real-time company news — funding rounds, hires, press mentions. Strike while the iron is hot. Take your raw ideas or voice memos and turn them into a polished weekly email. From brain dump to subscriber inbox. Ensure every lead has a follow-up date and a status update. No more leads falling through the cracks. ## Customer Success You shouldn't be the one answering "How do I reset my password?" — but you should be the one closing deals. Sort the tire kickers from the hot leads. Route inquiries to the right person or automated response. Help new clients set up their accounts, send welcome kits, and complete initial configuration. Handle Level 1 tech support for your platform. Resolve common issues and escalate what needs a human. ## Operations Automation Your right hand. These agents keep the gears greased so you don't get stuck in the admin trap. Clear out spam and highlight the three emails that actually need your brain. Protect your focus. Send bills and — more importantly — politely chase down the people who haven't paid them. Pull data and reports from multiple sources and unify them in one place. Your single source of truth. Protect your deep work time from being fragmented by random 15-minute meetings. ## Technical & Product Maintenance Unless you are a developer, tech debt will kill your productivity. These agents keep the lights on. Test new features or links before they go live to ensure nothing is broken. Turn your messy processes into clean Standard Operating Procedures (SOPs). Categorize and route incoming bug reports by severity. Nothing critical slips through. ## Using a Template Run `hive tui` to browse available agents, or explore the `examples/templates/` directory. Test the template to see how it works. Hive validates prerequisites and runs the agent automatically. Copy the template, update the goal, adjust nodes and edges, and make it yours. See [Build From Existing Agent](/building/build-with-existing-agent). Once you're happy with the results, [deploy](/building/deployment) your customized agent. ## Can't Find What You Need? If your use case isn't covered by an existing template, you can generate a custom agent from scratch using your coding agent. Run `claude> /hive` to start a guided agent creation session, or see [Build Your First Agent](/building/first-agent). You can also share your use case in our [Discord](https://discord.com/invite/MXE49hrKDk) — the community might already have a solution, or your idea could become the next template. # Who Is Hive For? Source: https://docs.adenhq.com/getting-started/who-is-hive-for Hive is built for developers who want to ship AI agents that automate real business processes in production Hive is designed for developers who are ready to move past demos and build AI agents that actually run in production. Whether you're automating processes for clients, building a product, or streamlining your own business — Hive helps you get there. ## Developer Profiles You're always learning and finding state-of-the-art tools because it defines your career. You've tried other AI tools but found them hard to apply to your customers' real needs. **What success looks like for you:** * Resell Hive-powered agents to your customers * Deliver production use cases with confidence * Start with simple templates, then build more complex automations * Become a trusted advisor who brings AI solutions to clients **Start here:** Browse the [use case templates](/getting-started/use-cases) and run one for a client need you already have. You have a real-world business process that needs automating. You're researching solutions and want something that works — not a science project. **What success looks like for you:** 1. Deploy an agent to production and get users to use it 2. Own the business process and know how to maintain it 3. Add integrations and expand the agent's capabilities as needs evolve 4. Get alerted on failures and debug issues when sessions go wrong **Start here:** Check out the [quickstart](/getting-started/quickstart) and build your [first agent](/building/first-agent). You believe developers who own business processes — not just write code — are the ones who thrive. You want to level up from coder to process owner. **What success looks like for you:** 1. Learn how business processes work by studying sample agents 2. Deploy a sample agent for your team to automate a process 3. Start owning the process and learning how to maintain it 4. Expand the agent's capabilities as the process evolves 5. Debug and fix agent issues independently **Start here:** Explore the [use case catalog](/getting-started/use-cases), then join our [Discord](https://discord.com/invite/MXE49hrKDk) to discover agent ideas from the community. You have a business with some traction but you're overwhelmed by repetitive tasks. You need multiple agents handling different parts of your operation so you can focus on what matters. **What success looks like for you:** 1. Deploy multiple agents from ready-made templates 2. Tweak agents to fit your specific needs 3. Program human-in-the-loop fallbacks so you get notified when agents can't handle something 4. Generate ad-hoc agents for new problems as they arise 5. Turn one-off agents into recurring automations, and recurring ones into fully autonomous processes 6. Get alerts when agents fail **Start here:** Browse the [use case templates](/getting-started/use-cases) — you'll find agents for sales, ops, customer support, and more. You have a product idea and need the right framework to build it on. You want something that will scale with you and not lock you into a dead end. **What success looks like for you:** 1. Build an MVP with Hive's agent generation framework 2. Add capabilities easily as your product grows 3. Trust the framework is future-proof 4. Wrap agents into your product with a clear deployment strategy 5. Monitor logs and costs across your user base **Start here:** Read the [core concepts](/building-agent/concepts/overview), then build your [first agent](/building/first-agent). ## The Common Denominator No matter which developer profile fits you, success with Hive always comes down to five things: Build your agent Fix what's broken Keep it running Ship to production Make it better Everything in Hive — from the templates to the debugging tools to the deployment pipeline — is designed to help you move through this cycle as fast as possible. ## Not Sure Where to Start? Browse use case templates organized by business function. Install Hive and run your first agent in under 10 minutes. # Introduction Source: https://docs.adenhq.com/index Build production AI agents that automate real business processes — create, debug, deploy, and iterate with confidence ## Your Developers' Success Is Our Success Aden Hive is a framework for building production-grade AI agents that automate real business processes. You define outcomes in natural language, and Hive generates adaptive agent graphs that self-improve when failures happen. We built Hive around a simple principle: **if our developers aren't winning, we aren't winning.** Every feature, every template, every tool exists to help you create agents that work in production — not just in demos. IT consultants, product builders, one-man CEOs, and developers automating real work. Browse ready-to-run agent templates for sales, support, ops, and more. Install Hive and reach your first success in under 10 minutes. Understand goal-driven development and agent architecture. ## What Developer Success Looks Like Success with Hive follows a clear path. Every developer who uses Hive should be able to: Define your goal in plain language or start from a template. Hive generates the agent graph and connection code for you. Run your agent interactively with `hive tui`, use three-level observability to see exactly what happened, and fix issues fast. Ship to production with `hive deploy` — locally via Docker or to Aden Cloud for zero-ops deployment. Own the business process. Get alerted on failures, monitor costs, and keep your agent reliable over time. Add integrations, expand use cases, and let the evolution loop improve your agent based on real-world outcomes. ## Quick Start ```bash theme={null} # Clone and install git clone https://github.com/adenhq/hive.git cd hive ./quickstart.sh # Build an agent with your coding agent claude> /hive # Test interactively hive tui # Run directly hive run exports/your_agent_name --input '{"key": "value"}' ``` ## Why Aden Traditional agent frameworks require you to manually wire workflows, handle failures reactively, and rebuild when things change. Aden flips this: **you describe outcomes, the framework builds and evolves itself**. | Traditional Frameworks | Aden Hive | | ---------------------------- | ---------------------------------- | | Hardcode agent workflows | Describe goals in natural language | | Manual graph definition | Auto-generated agent graphs | | Reactive error handling | Outcome-based adaptation | | Static tool configurations | Dynamic SDK-wrapped nodes | | No native intervention model | Built-in human-in-the-loop | | DIY monitoring | Three-level observability built in | Go from zero to a running agent with step-by-step guidance. Pick an existing agent, customize it, and make it yours. Local Docker deployment or zero-ops Aden Cloud — your choice. Three-level logging and AI-assisted debugging to fix issues fast. ## Community Join thousands of developers building production agents with Hive. Get help, share agent ideas, and connect with the community. Star the repo, report issues, and contribute templates. Talk to our team about your use case.