Getting Started

Getting Started

Prerequisites

• Python 3.11+
• uv package manager (recommended) or pip

Installation

From Source

git clone https://github.com/xhwSkhizein/agiwo.git
cd agiwo
uv sync

With pip

pip install agiwo

Configuration

Agiwo reads provider credentials from environment variables. Create a .env file in your project root:

# At least one provider is required
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DEEPSEEK_API_KEY=sk-...

Or export them in your shell:

export OPENAI_API_KEY=sk-...

Configuration Reference

Variable	Description	Default
OPENAI_API_KEY	OpenAI API key	none
ANTHROPIC_API_KEY	Anthropic API key	none
DEEPSEEK_API_KEY	DeepSeek API key	none
AGIWO_*	SDK-level settings in agiwo/config/settings.py	varies
AGIWO_CONSOLE_*	Console deployment settings	varies

Your First Agent

Create a file hello.py:

import asyncio

from agiwo.agent import Agent, AgentConfig
from agiwo.llm import OpenAIModel


async def main() -> None:
    agent = Agent(
        AgentConfig(
            name="assistant",
            description="A helpful assistant",
            system_prompt="You are a concise assistant. Answer in one sentence.",
        ),
        model=OpenAIModel(id="gpt-4o-mini", name="gpt-4o-mini"),
    )

    result = await agent.run("What is the capital of France?")
    print(result.response)

    await agent.close()


asyncio.run(main())

Run it:

uv run python hello.py
# The capital of France is Paris.

Streaming Responses

For real-time output, use run_stream():

async for event in agent.run_stream("Explain recursion in one sentence."):
    if event.type == "step_delta" and event.delta.content:
        print(event.delta.content, end="", flush=True)

Adding Tools

from agiwo.tool import BaseTool, ToolContext, ToolResult


class CalculatorTool(BaseTool):
    name = "calculator"
    description = "Perform basic arithmetic"

    def get_parameters(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "expression": {
                    "type": "string",
                    "description": "Math expression like '2 + 3'",
                },
            },
            "required": ["expression"],
        }

    async def execute(
        self,
        parameters: dict,
        context: ToolContext,
        abort_signal=None,
    ) -> ToolResult:
        try:
            result = eval(parameters["expression"], {"__builtins__": {}}, {})
            return ToolResult.success(
                tool_name=self.name,
                content=str(result),
            )
        except Exception as e:
            return ToolResult.failed(
                tool_name=self.name,
                error=str(e),
            )

Builtin Tools

Agiwo ships with several builtin tools that are automatically available:

Tool	Description
bash	Execute shell commands
bash_process	Manage long-running background processes
web_search	Search the web
web_reader	Fetch and extract web page content
memory_retrieval	Search workspace memory with hybrid retrieval

Switching Providers

Anthropic

from agiwo.llm import AnthropicModel

model = AnthropicModel(id="claude-sonnet-4-20250514", name="claude-sonnet-4")

DeepSeek

from agiwo.llm import DeepseekModel

model = DeepseekModel(id="deepseek-chat", name="deepseek-chat")

OpenAI-Compatible

from agiwo.llm import create_model_from_dict

model = create_model_from_dict(
    provider="openai-compatible",
    model_name="my-model",
    params={
        "base_url": "https://api.example.com/v1",
        "api_key_env_name": "MY_API_KEY",
    },
)

Next Steps

• Architecture Overview
• Multi-Agent
• Custom Tools
• Storage and Observability