Skip to main content

Documentation Index

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

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

The factory builds an agent whose tool is gated by requires_confirmation=True. The run pauses when the tool is called; the user approves or rejects via the /continue endpoint. 
"""Factory with HITL (Human-in-the-Loop) tool confirmation."""

import json

import httpx
from agno.agent import Agent, AgentFactory
from agno.db.postgres import PostgresDb
from agno.factory import RequestContext
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.tools import tool

db = PostgresDb(
    id="hitl-factory-db",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
)


@tool(requires_confirmation=True)
def get_top_hackernews_stories(num_stories: int) -> str:
    """Fetch top stories from Hacker News.

    Args:
        num_stories: Number of stories to retrieve.

    Returns:
        JSON string of story details.
    """
    response = httpx.get("https://hacker-news.firebaseio.com/v0/topstories.json")
    story_ids = response.json()
    stories = []
    for story_id in story_ids[:num_stories]:
        story = httpx.get(
            f"https://hacker-news.firebaseio.com/v0/item/{story_id}.json"
        ).json()
        story.pop("text", None)
        stories.append(story)
    return json.dumps(stories)


def build_hitl_agent(ctx: RequestContext) -> Agent:
    """Build an agent with a HITL tool for the calling tenant."""
    user_id = ctx.user_id or "anonymous"

    return Agent(
        model=OpenAIResponses(id="gpt-5.4"),
        db=db,
        tools=[get_top_hackernews_stories],
        instructions=(
            f"You are a news assistant for {user_id}. "
            "Use the get_top_hackernews_stories tool to fetch stories when asked."
        ),
        markdown=True,
    )


hitl_factory = AgentFactory(
    db=db,
    id="hitl-agent",
    name="HITL Agent",
    description="Factory agent with a tool requiring human confirmation before execution",
    factory=build_hitl_agent,
)

agent_os = AgentOS(
    id="hitl-factory-demo",
    description="Demo: factory agent with human-in-the-loop tool confirmation",
    agents=[hitl_factory],
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="05_hitl_factory:app", port=7777, reload=True)

​
Run the Example

git clone https://github.com/agno-agi/agno.git
cd agno

./scripts/demo_setup.sh
source .venvs/demo/bin/activate
./cookbook/scripts/run_pgvector.sh

python cookbook/05_agent_os/factories/agent/05_hitl_factory.py