Quickstart Guide

Get up and running with flujo in 5 minutes!

1. Install the Package

pip install flujo

2. Set Up Your API Keys

Create a .env file in your project directory:

cp .env.example .env

Add your API keys to .env:

OPENAI_API_KEY=your_key_here

3. Your First AgenticLoop

Create a new file hello_agentic.py:

from flujo.recipes.factories import make_agentic_loop_pipeline, run_agentic_loop_pipeline
from flujo.infra.agents import make_agent_async
from flujo.infra import init_telemetry
from flujo.domain.commands import AgentCommand, FinishCommand, RunAgentCommand

init_telemetry()

async def search_agent(query: str) -> str:
    print(f"   -> Tool Agent searching for '{query}'...")
    return "Python is a high-level, general-purpose programming language." if "python" in query.lower() else "No information found."

PLANNER_PROMPT = """
You are a research assistant. Use the `search_agent` to gather information.
When you have an answer, respond with `FinishCommand`.
"""
planner_agent = make_agent_async(
    "openai:gpt-4o",
    PLANNER_PROMPT,
    AgentCommand,
)

# Create the pipeline using the factory
pipeline = make_agentic_loop_pipeline(
    planner_agent=planner_agent,
    agent_registry={"search_agent": search_agent}
)

# Run the pipeline
result = await run_agentic_loop_pipeline(pipeline, "What is Python?")
print(result)

# Access trace information (FSD-12 feature)
if result.trace_tree:
    print(f"\n🌳 Execution Trace:")
    print(f"   Root span: {result.trace_tree.name}")
    print(f"   Status: {result.trace_tree.status}")
    print(f"   Duration: {result.trace_tree.end_time - result.trace_tree.start_time:.3f}s")
    print(f"   Steps: {len(result.step_history)}")

4. Run Your First Loop

python hello_agentic.py

You should see a short transcript of the planner running the search tool and finishing with an answer, plus trace information.

5. Debug with Tracing

After running your pipeline, you can inspect the execution trace:

# List recent runs
flujo lens list

# View trace for the most recent run (replace with actual run_id)
flujo lens trace <run_id>

# Show step details
flujo lens spans <run_id>

6. Next Steps

Now that you've seen the basics, explore the Tutorial and Concepts pages for a deeper dive.