> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opper.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent SDK Overview

> Build AI agents with tools, streaming, multi-agent composition, and MCP support

The Opper Agent SDK is part of the unified `opperai` SDK and is available for **Python** and **TypeScript** with a matching API.

<CardGroup cols={2}>
  <Card title="opperai on PyPI" icon="python" href="https://pypi.org/project/opperai/">
    `pip install opperai`
  </Card>

  <Card title="opperai on npm" icon="npm" href="https://www.npmjs.com/package/opperai">
    `npm install opperai`
  </Card>
</CardGroup>

<Note>
  On the standalone `opper-agents` (Python) or `@opperai/agents` (TypeScript) package? See [Migration & legacy SDKs](/agents/migration) for the upgrade path and links to the legacy repos.
</Note>

<CardGroup cols={2}>
  <Card title="Source" icon="github" href="https://github.com/opper-ai/opper-sdks">
    `opper-ai/opper-sdks` has the full source for both languages.
  </Card>

  <Card title="Working examples" icon="code" href="https://github.com/opper-ai/opper-sdks/tree/main/python/examples/agents">
    11 numbered examples per language. Each one runs against the live API.
  </Card>
</CardGroup>

| Language   | Package   | Imports                                        | Examples                                                                                                     |
| ---------- | --------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Python     | `opperai` | `from opperai.agent import Agent, tool, Hooks` | [`python/examples/agents/`](https://github.com/opper-ai/opper-sdks/tree/main/python/examples/agents)         |
| TypeScript | `opperai` | `import { Agent, tool } from "opperai"`        | [`typescript/examples/agents/`](https://github.com/opper-ai/opper-sdks/tree/main/typescript/examples/agents) |

## What an agent is

An agent runs a **think → act → observe** loop:

1. **Think**: the LLM is given the goal, instructions, and available tools, and decides what to do next.
2. **Act**: if the model called a tool, the SDK executes it and feeds the result back.
3. **Loop**: repeat until the model produces a final answer (and validates it against `output_schema` if set).

You define instructions, tools, and an optional output schema. The SDK handles the rest.

## Minimal agent

<CodeGroup>
  ```python Python theme={null}
  from opperai.agent import Agent, tool

  @tool
  def get_weather(city: str) -> str:
      """Get the current weather for a city."""
      return f"Sunny, 22°C in {city}"

  agent = Agent(
      name="weather-assistant",
      instructions="You are a helpful weather assistant.",
      tools=[get_weather],
  )

  result = await agent.run("What's the weather in Paris?")
  print(result.output)
  print(result.meta.usage.total_tokens)
  ```

  ```typescript TypeScript theme={null}
  import { z } from "zod";
  import { Agent, tool } from "opperai";

  const getWeather = tool({
    name: "get_weather",
    description: "Get the current weather for a city",
    parameters: z.object({ city: z.string() }),
    execute: async ({ city }) => `Sunny, 22°C in ${city}`,
  });

  const agent = new Agent({
    name: "weather-assistant",
    instructions: "You are a helpful weather assistant.",
    tools: [getWeather],
  });

  const result = await agent.run("What's the weather in Paris?");
  console.log(result.output);
  console.log(result.meta.usage.totalTokens);
  ```
</CodeGroup>

## Patterns

| Pattern           | Page                                                    | Source example                        |
| ----------------- | ------------------------------------------------------- | ------------------------------------- |
| Tools             | [Tools](/agents/patterns/tools)                         | `02_agent_with_tools`                 |
| Structured output | [Structured output](/agents/patterns/structured-output) | `01_agent_with_schema`                |
| Streaming         | [Streaming](/agents/patterns/streaming)                 | `03_streaming`                        |
| Lifecycle hooks   | [Hooks](/agents/patterns/hooks)                         | `04_hooks_logging`, `05_hooks_timing` |
| Multi-agent       | [Multi-agent](/agents/patterns/multi-agent)             | `07_agent_as_tool`, `08_multi_agent`  |
| Multi-turn        | [Conversation](/agents/patterns/conversation)           | `10_conversation`                     |
| MCP               | [MCP](/agents/patterns/mcp)                             | `09_mcp_stdio`                        |

Tracing is on by default. Every agent run, LLM call, and tool execution shows up as a structured trace tree in the [Opper dashboard](https://platform.opper.ai/).

## When to use it

Reach for the Agent SDK when the work involves choosing between tools, chaining steps based on intermediate results, or coordinating multiple specialists. For a single deterministic LLM call, use [`opper.call()`](/v3-api-reference/functions/call-function-by-name) directly.