Skip to main content

Quick Start

One-shot query​

Use the top-level query() function for single-shot interactions:

import asyncio
from agentix import AgentixAgentOptions, query, ResultMessage

async def main():
    options = AgentixAgentOptions(
        name="my-agent",
        provider="openai",
        model="gpt-4o",
        system_prompt="You are a helpful assistant.",
    )

    async for msg in query("What is 2 + 2?", options=options):
        if isinstance(msg, ResultMessage):
            print(msg.result)

asyncio.run(main())

Multi-turn session​

Use AgentixClient for multi-turn conversations. The client automatically maintains session state between calls:

import asyncio
from agentix import AgentixAgentOptions, AgentixClient, AssistantMessage, ResultMessage, TextBlock

async def main():
    options = AgentixAgentOptions(
        name="assistant",
        provider="anthropic",
        model="claude-sonnet-4-20250514",
        system_prompt="You are a senior software engineer.",
    )

    async with AgentixClient(options) as client:
        # First turn
        async for msg in client.query("Explain Python generators in 3 sentences."):
            if isinstance(msg, AssistantMessage):
                for block in msg.content:
                    if isinstance(block, TextBlock):
                        print(block.text, end="")
            if isinstance(msg, ResultMessage):
                print()  # newline after response

        # Second turn — agent remembers context
        async for msg in client.query("Now show me a practical example."):
            if isinstance(msg, ResultMessage):
                print(msg.result)

asyncio.run(main())

Environment variable configuration​

Instead of passing options programmatically, configure via environment:

export AGENTIX_PROVIDER=openai
export AGENTIX_MODEL=gpt-4o
export AGENTIX_API_KEY=sk-...
export AGENTIX_CWD=/path/to/project

Then create a minimal options object:

options = AgentixAgentOptions(name="my-agent")
# Provider, model, and API key are picked up from environment

Custom tools​

Register synchronous or asynchronous tools on the client:

from agentix import AgentixAgentOptions, AgentixClient, ResultMessage

options = AgentixAgentOptions(
    name="tool-demo",
    provider="openai",
    system_prompt="You have access to a calculator tool.",
)

async def main():
    async with AgentixClient(options) as client:

        @client.tool(name="Calculator", description="Evaluate a math expression.")
        def calculator(expression: str) -> str:
            try:
                return str(eval(expression))  # demo only — don't use eval in production
            except Exception as e:
                return f"Error: {e}"

        async for msg in client.query("What is 123 * 456?"):
            if isinstance(msg, ResultMessage):
                print(msg.result)  # "56088"

asyncio.run(main())

Handling errors​

from agentix import AgentixAgentOptions, AgentixClient, ResultMessage

async with AgentixClient(options) as client:
    async for msg in client.query("Do something"):
        if isinstance(msg, ResultMessage):
            if msg.is_error:
                print(f"Error: {msg.result} (subtype={msg.subtype})")
            else:
                print(msg.result)

ResultMessage fields​

FieldDescription
is_errorTrue if the agent stopped due to an error
resultFinal text result (never raises)
subtype"error_max_turns", "error_max_budget_usd", "error_timeout", "error_unknown", or None
stop_reason"end_turn", "max_tokens", "interrupt", "max_iterations"
session_idSession ID for this run
usageToken usage dict including turn_timings and tool_metrics

Next steps​