agenthelm 0.2.0

A production-ready, observable, and reliable AI agent orchestration framework.

AgentHelm

Production-Ready Orchestration for AI Agents.

---

AgentHelm is a lightweight Python framework for building AI agents with a focus on production-readiness. It provides the essential orchestration layer to make your agents observable, reliable, and safe.

In the rapidly evolving world of AI agents, many frameworks focus on rapid prototyping. AgentHelm is different. It's built on the premise that for agents to be trusted in real-world, production environments, they need the same level of observability and control as traditional software.

If you've ever struggled to debug a failing agent or worried about deploying an agent that interacts with real-world systems, AgentHelm is for you.

Key Features

• Traceable Execution: Automatically log every tool call, its inputs, outputs, errors, and execution time. Get a complete, structured audit trail of your agent's actions.
• Human-in-the-Loop: Mark sensitive tools (e.g., charge_credit_card) with a @tool(requires_approval=True) decorator to ensure a human must approve the action before it runs.
• Resilient Workflows: Define automatic retries for flaky tools that might fail due to transient network errors.
• Transactional Safety: Implement automatic rollbacks for multi-step workflows. If a step fails, AgentHelm can run compensating actions to undo the previous steps.

---

Observability & Trace Explorer (v0.2.0 New!)

AgentHelm now provides enhanced observability features, allowing you to store, query, and analyze your agent's execution traces with ease.

Storage Backends

By default, AgentHelm stores traces in a JSON file (cli_trace.json). You can now choose between different storage backends:

• JSON Storage: Simple file-based storage (.json files). Ideal for local development and smaller projects.
• SQLite Storage: A robust, file-based relational database (.db files). Offers efficient querying capabilities for larger trace datasets.

Specify your desired storage backend using the --trace-file option with either a .json or .db extension.

CLI Trace Explorer

Use the agenthelm traces command to interact with your stored execution traces:

List Traces

List recent traces with pagination:

agenthelm traces list --limit 5 --offset 0 --trace-file my_traces.db
agenthelm traces list --json # Output in JSON format

Show Trace Details

View detailed information for a specific trace ID:

agenthelm traces show 0 --trace-file my_traces.db

Filter Traces

Filter traces by various criteria:

agenthelm traces filter --tool-name read_file --status failed --date-from 2025-11-01 --trace-file my_traces.db
agenthelm traces filter --min-time 1.0 --confidence-max 0.5 --json

Export Traces

Export filtered traces to different formats (CSV, JSON, Markdown):

agenthelm traces export --output report.csv --format csv --status failed --trace-file my_traces.db
agenthelm traces export --output all_traces.json --format json
agenthelm traces export --output summary.md --format md --tool-name search_web

---

The Agent Helm Ecosystem

graph TD
subgraph "AgentHelm Ecosystem"
    direction LR
    A[User Task] --> AH(AgentHelm Orchestrator)
    AH --  Sends prompt/tools --> LLM(LLM Engine e.g., Mistral)
    LLM --  Returns tool_call --> AH
    AH --  Executes tool --> T1[Tool: get_weather]
    AH --  Executes tool --> T2[Tool: post_tweet]
    AH --  Executes tool --> T3[Tool: ...]
    T1 --  Returns result --> AH
    T2 --  Returns result --> AH
    AH --  Sends result to LLM --> LLM
    LLM -- Returns final answer --> AH
    AH -- Returns to User --> UO[Final Output]
end

style AH fill:#007BFF,stroke:#333,stroke-width:2px,color:#fff
style LLM fill:#FFC107,stroke:#333,stroke-width:2px,color:#000        

The Trace Explorer

graph TD
    A[Agent Execution] --> B{Storage Backend}
    B -->|JSON| C[JSON File]
    B -->|SQLite| D[SQLite DB]
    C --> E[CLI Trace Explorer]
    D --> E
    E --> F[traces list]
    E --> G[traces show]
    E --> H[traces filter]
    E --> I[traces export]
    I -->|CSV| J[report.csv]
    I -->|JSON| K[data.json]
    I -->|Markdown| L[summary.md]
    style B fill: #007BFF, stroke: #333, stroke-width: 2px, color: #fff
    style E fill: #FFC107, stroke: #333, stroke-width: 2px, color: #000

Quick Start

1. Installation

pip install agenthelm

2. Create your Tools

Create a Python file (e.g., tools.py) and define your functions with the @tool decorator. AgentHelm automatically parses the function signature to build the contract.

# tools.py
from orchestrator import tool

@tool()
def get_weather(city: str) -> str:
    """Gets the current weather for a given city."""
    if city == "New York":
        return "It is 24°C and sunny in New York."
    else:
        return f"Sorry, I don't know the weather for {city}."

@tool(requires_approval=True)
def post_tweet(message: str) -> dict:
    """Posts a message to a social media feed."""
    print(f"TWEETING: {message}")
    return {"status": "posted"}

3. Environment Variables

AgentHelm requires API keys for the Large Language Models (LLMs) it interacts with. Set these as environment variables:

• Mistral AI: Set MISTRAL_API_KEY. Optionally, set MISTRAL_MODEL_NAME (defaults to mistral-small-latest).

  export MISTRAL_API_KEY="your_mistral_api_key_here"
  # export MISTRAL_MODEL_NAME="mistral-large-latest"
  

• OpenAI: Set OPENAI_API_KEY. Optionally, set OPENAI_MODEL_NAME (defaults to gpt-4).

  export OPENAI_API_KEY="your_openai_api_key_here"
  # export OPENAI_MODEL_NAME="gpt-3.5-turbo"
  

4. Run the Agent

Use the agenthelm command-line tool (or python -m main) to run your agent. The CLI handles everything from setting up the agent to running the reasoning loop and logging the traces.

# Run the agent from your terminal
agenthelm run \
  --agent-file examples/cli_tools_example/my_agent_tools.py \
  --task "What is the weather in New York?"

# For verbose output, add the -v or --verbose flag
agenthelm run \
  --agent-file examples/cli_tools_example/my_agent_tools.py \
  --task "What is the weather in New York?" \
  --llm-type mistral \
  --verbose

# To specify the output trace file, use the --trace-file option
agenthelm run \
  --agent-file examples/cli_tools_example/my_agent_tools.py \
  --task "What is the weather in New York?" \
  --trace-file my_trace.json

This will produce a detailed trace file (by default cli_trace.json), giving you a perfect record of the agent's execution.

Documentation

For comprehensive guides, tutorials, and API reference, please visit our official documentation site: https://hadywalied.github.io/agenthelm/

Contributing

We welcome contributions! Please feel free to open an issue or submit a pull request.