Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adenhq.com/llms.txt

Use this file to discover all available pages before exploring further.

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 to find a starting point that matches your workflow.

​
1. Copy the Base Agent

From exports/: 
cp -R exports/support_ticket_agent exports/support_ticket_agent_v2
Or start from an example agent: 
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:

​
4. Validate the New Agent

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

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

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.
Use explicit suffixes for major revisions:
  • agent_name_v2
  • agent_name_v3
Avoid in-place edits to production agents without version history.

​
Next Steps

Testing

Strengthen regression coverage and edge-case checks

Key Concepts

Revisit runtime and evolution concepts before major refactors

Deployment

Prepare your refined agent for production

Iteration

Evolve your agent based on production feedback