> ## 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.

# Quickstart

> Install, set your API key, and run your first agent

<Info>
  Source: [`opper-ai/opper-sdks`](https://github.com/opper-ai/opper-sdks). The agent layer ships inside the `opperai` package, so there's nothing extra to install.
</Info>

## Build your first agent

<Steps>
  <Step title="Install">
    <CodeGroup>
      ```bash Python theme={null}
      pip install opperai
      # or: uv add opperai
      ```

      ```bash TypeScript theme={null}
      npm install opperai zod
      # or: pnpm add opperai zod
      ```
    </CodeGroup>

    Requirements: Python 3.10+ or Node.js 18+. TypeScript users need Zod v4.
  </Step>

  <Step title="Set your API key">
    ```bash theme={null}
    export OPPER_API_KEY="your-api-key"
    ```

    Get a key at [platform.opper.ai](https://platform.opper.ai/). You can also pass it explicitly via `client={"api_key": "..."}` (Python) or `client: { apiKey: "..." }` (TypeScript) on the `Agent` constructor.
  </Step>

  <Step title="Run an agent">
    <CodeGroup>
      ```python Python theme={null}
      import asyncio
      from opperai.agent import Agent, tool

      @tool
      def add(a: int, b: int) -> int:
          """Add two numbers."""
          return a + b

      @tool
      def multiply(a: int, b: int) -> int:
          """Multiply two numbers."""
          return a * b

      async def main() -> None:
          agent = Agent(
              name="math-agent",
              instructions="You are a helpful math assistant. Show the steps.",
              tools=[add, multiply],
          )

          result = await agent.run("What is 5 + 3, then multiplied by 2?")

          print("Output:", result.output)
          print("Iterations:", result.meta.iterations)
          print("Tokens:", result.meta.usage.total_tokens)

      asyncio.run(main())
      ```

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

      const add = tool({
        name: "add",
        description: "Add two numbers",
        parameters: z.object({ a: z.number(), b: z.number() }),
        execute: async ({ a, b }) => a + b,
      });

      const multiply = tool({
        name: "multiply",
        description: "Multiply two numbers",
        parameters: z.object({ a: z.number(), b: z.number() }),
        execute: async ({ a, b }) => a * b,
      });

      const agent = new Agent({
        name: "math-agent",
        instructions: "You are a helpful math assistant. Show the steps.",
        tools: [add, multiply],
      });

      const result = await agent.run("What is 5 + 3, then multiplied by 2?");

      console.log("Output:", result.output);
      console.log("Iterations:", result.meta.iterations);
      console.log("Tokens:", result.meta.usage.totalTokens);
      ```
    </CodeGroup>

    The agent picks `add(5, 3) = 8`, then `multiply(8, 2) = 16`, then returns. Every tool call is captured in `result.meta.tool_calls` (Python) / `result.meta.toolCalls` (TS).
  </Step>

  <Step title="Run an end-to-end example">
    The repo has numbered examples, each showing one pattern. Run them directly:

    <CodeGroup>
      ```bash Python theme={null}
      git clone https://github.com/opper-ai/opper-sdks
      cd opper-sdks/python
      uv run python examples/agents/00_first_agent.py
      ```

      ```bash TypeScript theme={null}
      git clone https://github.com/opper-ai/opper-sdks
      cd opper-sdks/typescript
      npx tsx examples/agents/00-your-first-agent.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## What's next

<CardGroup cols={2}>
  <Card title="Tools" icon="wrench" href="/agents/patterns/tools">
    Define tools the agent can call.
  </Card>

  <Card title="Structured output" icon="code" href="/agents/patterns/structured-output">
    Return validated, typed data instead of free text.
  </Card>

  <Card title="Streaming" icon="wave-pulse" href="/agents/patterns/streaming">
    Watch the agent work as it happens.
  </Card>

  <Card title="Multi-agent" icon="sitemap" href="/agents/patterns/multi-agent">
    Compose specialists into a coordinator.
  </Card>
</CardGroup>