aisuite README

The project's README from github.com/andrewyng/aisuite. As one markdown file: README.md.

OpenWorker

OpenWorker

A desktop AI coworker, built on aisuite — now in its own repository: andrewyng/openworker.

OpenWorker chats, does deep research, and carries out real tasks on your computer — reading files with permission, connecting to Slack/email, producing PDFs, documents, and spreadsheets, and running scheduled automations. Bring your own API key (OpenAI, Anthropic, Google) or run fully local with Ollama; your data stays on your machine.

⬇ Download for macOS macOS 13+ (Apple Silicon)  ·  ⬇ Download for Windows Windows 10/11 (x64)  ·  Quickstart

OpenWorker development has moved to the new repo. A historical snapshot of its source remains in openworker-archive/.


aisuite

PyPI Code style: black

aisuite is a lightweight Python library for building with LLMs, in two layers: a unified Chat Completions API across providers, and an Agents API with tools and toolkits on top. aisuite also powers OpenWorker, a desktop AI coworker developed in its own repository:

┌───────────────────────────────────────────────┐
│          OpenWorker  (separate repo)          │   agent harness for doing everyday tasks
├───────────────────────────────────────────────┤
│        Agents API  ·  Toolkits  ·  MCP        │   build agents across multiple LLMs
├───────────────────────────────────────────────┤
│             Chat Completions API              │   one API across multiple LLM providers
├────────┬───────────┬────────┬────────┬────────┤
│ OpenAI │ Anthropic │ Google │ Ollama │ Others │
└────────┴───────────┴────────┴────────┴────────┘

Installation

Install the base package, or include the SDKs of the providers you plan to use:

pip install aisuite               # base package, no provider SDKs
pip install 'aisuite[anthropic]'  # with a specific provider's SDK
pip install 'aisuite[all]'        # with all provider SDKs

You'll also need API keys for the providers you call — the Chat Completions quickstart covers key setup and your first calls.

Looking for the OpenWorker desktop app? Downloads are on its releases page.

Chat Completions — one API across providers

The chat API provides a high-level abstraction for model interactions. It supports all core parameters (temperature, max_tokens, tools, etc.) in a provider-agnostic way, and standardizes request and response structures so you can focus on logic rather than SDK differences.

Model names use the format <provider>:<model-name>; aisuite routes the call to the right provider with the right parameters:

import aisuite as ai
client = ai.Client()

models = ["openai:gpt-4o", "anthropic:claude-3-5-sonnet-20240620"]

messages = [
    {"role": "system", "content": "Respond in Pirate English."},
    {"role": "user", "content": "Tell me a joke."},
]

for model in models:
    response = client.chat.completions.create(
        model=model,
        messages=messages,
        temperature=0.75
    )
    print(response.choices[0].message.content)

→ Quickstart: docs/chat-completions-quickstart.md — install, key setup, local models, and more examples.

Streaming

Pass stream=True to get an iterator of OpenAI-shaped chunks from any supporting provider (OpenAI, Anthropic, Ollama, and OpenAI-compatible endpoints) — the same loop works across all of them:

for chunk in client.chat.completions.create(model=model, messages=messages, stream=True):
    print(chunk.choices[0].delta.content or "", end="", flush=True)

The async variant is await client.chat.completions.acreate(..., stream=True), iterated with async for. Tool calls stream too: schema dicts and callables are passed to the model as usual, and the chunks carry incremental delta.tool_calls fragments for you to assemble and execute (streaming is manual tool calling — it can't be combined with max_turns).

Agents — give models real tools

aisuite turns tool calling into a one-liner: pass plain Python functions and it generates the schemas, executes the calls, and feeds results back to the model.

Tool calling with max_turns

def will_it_rain(location: str, time_of_day: str):
    """Check if it will rain in a location at a given time today.

    Args:
        location (str): Name of the city
        time_of_day (str): Time of the day in HH:MM format.
    """
    return "YES"

client = ai.Client()
response = client.chat.completions.create(
    model="openai:gpt-4o",
    messages=[{
        "role": "user",
        "content": "I live in San Francisco. Can you check for weather "
                   "and plan an outdoor picnic for me at 2pm?"
    }],
    tools=[will_it_rain],
    max_turns=2  # Maximum number of back-and-forth tool calls
)
print(response.choices[0].message.content)

With max_turns set, aisuite sends your message, executes any tool calls the model requests, returns the results to the model, and repeats until the conversation completes. response.choices[0].intermediate_messages carries the full tool interaction history if you want to continue the conversation.

Prefer full manual control? Omit max_turns and pass OpenAI-format JSON tool specs — aisuite returns the model's tool-call requests and you run the loop yourself. See examples/tool_calling_abstraction.ipynb for both styles.

The Agents API

For longer-running, structured work there is a first-class Agents API: declare an agent once, run it with a Runner, and attach toolkits — prebuilt, sandboxed tool families for files, git, and shell:

import aisuite as ai
from aisuite import Agent, Runner

agent = Agent(
    name="repo-helper",
    model="anthropic:claude-sonnet-4-6",
    instructions="You are a careful repo assistant. Use your tools to answer from the code.",
    tools=[*ai.toolkits.files(root="."), *ai.toolkits.git(root=".")],
)

result = Runner.run(agent, "What changed in the last commit? Summarize in 3 bullets.")
print(result.final_output)

The Agents API also gives you the pieces a production harness needs:

MCP tools

aisuite natively supports the Model Context Protocol, so any MCP server's tools can be handed to a model without boilerplate (pip install 'aisuite[mcp]'):

client = ai.Client()
response = client.chat.completions.create(
    model="openai:gpt-4o",
    messages=[{"role": "user", "content": "List the files in the current directory"}],
    tools=[{
        "type": "mcp",
        "name": "filesystem",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    }],
    max_turns=3
)
print(response.choices[0].message.content)

For reusable connections, security filters, and tool prefixing, use the explicit MCPClient.

→ Quickstart: docs/agents-quickstart.md — manual tool handling, the full Agents API, policies, state stores, and MCP in depth.

Extending aisuite: Adding a Provider

New providers can be added by implementing a lightweight adapter. The system uses a naming convention for discovery:

Element Convention
Module file <provider>_provider.py
Class name <Provider>Provider (capitalized)

Example:

# providers/openai_provider.py
class OpenaiProvider(BaseProvider):
    ...

This convention ensures consistency and enables automatic loading of new integrations.

Contributing

Contributions are welcome. Please review the Contributing Guide and join our Discord for discussions.

License

Released under the MIT License — free for commercial and non-commercial use.

aisuite (andrewyng/aisuite)

Searching Database…

16.3K ·GitHub
Aisuite
What is this?aisuite is a lightweight Python library that gives you a single unified Chat Completions API across many Generative AI providers, plus an Agents API with tools, toolkits, and MCP support built on top.
Is it a framework or just a wrapper library?It is a Python library/SDK, not a standalone app: it normalizes requests and responses across providers so you can swap providers by changing one model-name string, and it also has a separate Agents API layer for tool-using agents.
How do I add it to a project?Install the base package via pip, plus the SDK extras for whichever providers you plan to use (e.g. 'pip install aisuite[mcp]' for MCP support), then set API keys for those providers.
Which providers and tools does it support out of the box?It covers OpenAI, Anthropic, Google, Mistral, Hugging Face, AWS, Cohere, Ollama, OpenRouter, Requesty and more, and it can call any MCP server's tools directly without extra boilerplate.
Can I combine streaming with multi-turn tool calling?No — streaming tool calls require you to manually assemble and execute the incremental delta.toolcalls fragments yourself; it cannot be combined with the automatic maxturns tool-calling loop.
Who is this for versus the OpenWorker app?aisuite is for developers building their own LLM apps/agents in Python; OpenWorker is a separate pre-built desktop AI coworker app (for macOS/Windows) that happens to be built on top of aisuite.
Can I run it without cloud API keys?Yes — aisuite supports Ollama as a provider, so you can run models locally instead of calling a cloud API.
How do I let the model call my own Python functions?Pass plain Python functions as tools and aisuite auto-generates the schemas, executes the calls, and feeds the results back to the model — optionally with 'max_turns' to run the full loop automatically.
What does the Agents API add beyond simple tool calling?It lets you declare an agent once, run it with a Runner, attach prebuilt sandboxed toolkits for files, git and shell, set tool-approval policies, persist/resume state (in-memory, file, or Postgres), and capture artifacts and traces.
How do I add support for a new provider?Create a module named provider.py with a capitalized Provider class following aisuite's naming convention, and it will be automatically discovered and loaded.
What is OpenWorker?OpenWorker is a desktop AI coworker app built on aisuite that chats, does deep research, and performs real tasks on your computer (reading files, connecting to Slack/email, producing documents) using your own API key or fully local via Ollama; it now lives in its own repository (andrewyng/openworker).
What are similar projects?turnstone, trueforge, swarm, evenfire, zhizhi-agent-runtime, openai-agents-python, bareloop, composio
Which topics is it in?function-calling, tool-calling, openai-compatible, model-context-protocol, agent-orchestration, streaming, agentic-ai, sdk, multi-agent, agents, rest-api, openai
Creator
andrewyng
Size
4.3 MB
Stars
16.3K
Updated
CommitSep 18Releasev0.1.3Jul 20
Age
2y
Commits · 90 Days