AIAgent Python API Reference

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-opus-4.6",
    max_iterations=10,
    enabled_toolsets=["file", "terminal"],
    quiet_mode=True,
)
response = agent.chat("List the files in the current directory")
print(response)

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-opus-4.6",
    max_iterations=90,
    quiet_mode=True,
)

def chat(self, message: str, stream_callback: Optional[callable] = None) -> str:
    """Simple interface — returns final response string."""

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-opus-4.6",
    quiet_mode=True,
    enabled_toolsets=["file"],
)

response = agent.chat("How many Python files are in the current directory?")
print(response)
# → "There are 12 Python files in the current directory."

def run_conversation(
    self,
    user_message: str,
    system_message: str = None,
    conversation_history: list = None,
    task_id: str = None,
    stream_callback: Optional[callable] = None,
    persist_user_message: Optional[str] = None,
) -> dict:
    """Full interface — returns dict with final_response + messages."""

{
    "final_response": str,          # The model's last text response
    "last_reasoning": str | None,   # Reasoning content from the last assistant turn (if any)
    "messages": list,               # Full OpenAI-format message history
    "completed": bool,              # True if loop ended cleanly (no tool calls remain)
    "partial": bool,                # True if stopped due to invalid tool calls
    "api_calls": int,               # Number of LLM API calls made
    "interrupted": bool,            # True if an interrupt was requested during the run
    "response_previewed": bool,     # True if the response was streamed/previewed before return
    # "interrupt_message": str      # Only present when interrupted=True and a message triggered it
}

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-opus-4.6",
    quiet_mode=True,
    enabled_toolsets=["file", "terminal"],
)

# First turn
result1 = agent.run_conversation("Create a file called hello.txt with 'Hello, World!'")
print(result1["final_response"])

# Continue the conversation with the previous history
result2 = agent.run_conversation(
    "Now read that file back and tell me its contents.",
    conversation_history=result1["messages"],
)
print(result2["final_response"])

result = agent.run_conversation(
    user_message="Analyze the security of this codebase.",
    system_message="You are a security auditor. Focus on authentication flows and input validation.",
    task_id="sec-audit-001",
)

while api_call_count < self.max_iterations and self.iteration_budget.remaining > 0:
    response = client.chat.completions.create(
        model=model,
        messages=messages,
        tools=tool_schemas,
    )
    if response.tool_calls:
        for tool_call in response.tool_calls:
            result = handle_function_call(tool_call.name, tool_call.args, task_id)
            messages.append(tool_result_message(result))
        api_call_count += 1
    else:
        return response.content  # No more tool calls — done

# User message
{"role": "user", "content": "your message"}

# Assistant message with optional tool calls
{"role": "assistant", "content": "...", "tool_calls": [...], "reasoning": "..."}

# Tool result
{"role": "tool", "tool_call_id": "call_abc123", "content": "{...json...}"}

# System message
{"role": "system", "content": "..."}

tools/registry.py      ← no external deps; imported by all tool files
       ↑
tools/*.py             ← each calls registry.register() at import time
       ↑
model_tools.py         ← imports tools/registry, triggers tool discovery
       ↑
run_agent.py           ← imports model_tools; defines AIAgent

gauss acp          # Start the ACP server (used by VS Code, Zed, JetBrains extensions)

pip install "gauss-agent[acp]"