Quick Start

This guide will get you up and running with YosrAI in under 5 minutes.

Set Up Environment

We strongly recommend uv for its speed, but conda works too.

Option A: Using uv (Recommended)

# Create virtual environment
uv venv

# Activate it
source .venv/bin/activate

Option B: Using conda

conda create -n yosrai python=3.11
conda activate yosrai

Installation

Install YosrAI using pip or uv. We recommend installing with the specific provider extras you need:

# Core installation (Ollama only)
pip install yosrai

# With OpenAI support (includes CLI)
pip install "yosrai[openai]"

# With Anthropic support
pip install "yosrai[anthropic]"

# With Google Gemini support
pip install "yosrai[google]"

# Install everything
pip install "yosrai[all]"

Or using uv (recommended):

# Install with uv
uv pip install -e .

# With optional dependencies
uv pip install -e ".[openai,anthropic,google]"

Your First Agent

Create a file named app.py:

from yosrai.engine import Agent, Context

# 1. Define the Agent
agent = Agent(
    name="Poet",
    model="ollama/llama3", 
    instructions="You are a creative poet."
)

# 2. Define the Context (Input)
ctx = Context(input="Write a haiku about code.")

# 3. Run
response = agent.run(ctx)
print(response)

Run it:

python app.py

Enable Transparent Execution

Watch your agent think step-by-step:

# Enable verbose output
agent = Agent(
    name="Poet",
    model="ollama/llama3",
    instructions="You are a creative poet.",
    verbose=True  # <-- See the reasoning process
)

# Or capture execution for replay
result = agent.run("Write a haiku about code.", trace=True)
result.replay()  # Review execution with timing

Export Your Agent

Generate code, diagrams, and blueprints:

# Export as runnable Python code
code = agent.to_code()
print(code)

# Export as JSON blueprint
blueprint = agent.to_blueprint()

Adding Tools

Agents become powerful when you give them tools.

from yosrai.engine import Agent, Context, tool

@tool
def calculator(a: int, b: int) -> int:
    """Adds two numbers."""
    return a + b

agent = Agent(
    name="MathBot",
    model="ollama/llama3",
    instructions="Use the calculator tool.",
    tools=[calculator]
)

print(agent.run(Context(input="What is 5 + 7?")))

For common tasks (Files, Shell), check out yosrai.toolkit:

from yosrai.toolkit import FileToolkit
tools = FileToolkit(root_dir="./workspace").get_tools()

Deploy as a Service

Turn your agent into a REST API:

from yosrai import ServiceWrapper

# Wrap your agent
service = ServiceWrapper(agent, title="My Poet API")

# Run the service
service.run(host="0.0.0.0", port=8000)

Now visit http://localhost:8000/docs for Swagger UI, or call via API:

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{"input": "Write a poem about stars"}'

Agent Presets (Quick Start)

Skip configuration and use pre-built agents:

from yosrai import Agent

# One-liner agents
researcher = Agent.from_preset("researcher")
writer = Agent.from_preset("writer")
coder = Agent.from_preset("coder")

# Ready to use
result = researcher.run("Explain quantum computing")
print(result)

CLI Tool (Quick Commands)

YosrAI becomes a command-line tool:

# Validate blueprints
yosrai validate blueprint.json

# Execute from blueprint
yosrai run agent_blueprint.json --input "Hello"

# Generate diagrams
yosrai diagram workflow.json -o docs/diagram.md

# Interactive chat
yosrai chat --preset researcher

# Create new projects
yosrai new agent MyAgent --preset assistant

Launch YosrAI Studio

Visual browser-based interface for agents and workflows:

# Launch Studio on http://localhost:8080
yosrai studio

In Studio you can: - 📋 Discover blueprints from studio_files/ - 🔧 View Mermaid diagrams and generated Python code - ▶️ Execute workflows with custom inputs - 🤝 Handle human approval workflows with interactive dialogs - 📊 Watch real-time execution logs with event streaming

Example: Human Approval Workflow

Create studio_files/approval_workflow.json:

{
  "type": "Workflow",
  "name": "ContentApproval",
  "steps": [
    {
      "agent": {
        "type": "Agent",
        "name": "Writer",
        "instructions": "Write content.",
        "model": "openai/gpt-4o-mini"
      }
    },
    {
      "agent": {
        "type": "HumanAgent",
        "name": "Approver",
        "instructions": "Review and type APPROVE or feedback."
      }
    }
  ]
}

Then in Studio: 1. Select ContentApproval from sidebar 2. Click "Run Engine" 3. Enter input (e.g., "Write about AI") 4. Dialog appears when workflow reaches HumanAgent 5. Type approval or feedback 6. Workflow completes with results

Conversation Mode

Natural multi-turn conversations:

from yosrai import Agent

agent = Agent.from_preset("assistant")

with agent.conversation() as chat:
    response1 = chat.send_message("Hello!")
    response2 = chat.send_message("What's my name?")
    print(f"Total cost: ${chat.total_usage.cost:.4f}")

Cost Tracking

Monitor usage automatically:

agent = Agent.from_preset("assistant")
result = agent.run("Write a summary")

print(f"Cost: ${agent.last_usage.cost:.4f}")
print(f"Tokens: {agent.last_usage.total_tokens}")