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

# Quickstart

> Deploy your first agent and invoke it in 5 minutes — TypeScript, Python, Go, or curl.

This guide walks you from zero to a running agent that you can chat with
via the BeeOS public OpenAPI. The same flow works against
`http://localhost:8095` for local dev or `https://openapi.beeos.ai` for
production.

## Prerequisites

* A BeeOS account at [beeos.ai](https://beeos.ai).
* A **User API Key** (`oag_...`) from **Settings → API Keys**. The key
  acts as a long-lived bearer credential bound to your user — see
  [Authentication](/authentication) for the credential format and
  rotation guidance.

## 1. Install the SDK

<CodeGroup>
  ```bash npm theme={null}
  npm install @beeos-ai/sdk
  ```

  ```bash go theme={null}
  go get github.com/beeos-ai/sdk-go
  ```

  ```bash python theme={null}
  python -m pip install beeos
  ```

  ```bash curl theme={null}
  # No installation needed — use curl directly.
  ```
</CodeGroup>

<Note>
  The published `@beeos-ai/sdk` is auto-generated from the OpenAPI contract
  using OpenAPI Generator (`typescript-fetch`). It exposes a
  `Configuration` value plus one class per OpenAPI tag — `DeployApi`,
  `InstancesApi`, `AgentsApi`, `TasksApi`, `ConversationsApi`,
  `FilesApi`. There is no `BeeOS` umbrella client.
</Note>

## 2. Configure the client

<CodeGroup>
  ```typescript TypeScript theme={null}
  import {
    Configuration,
    DeployApi,
    InstancesApi,
    AgentsApi,
  } from "@beeos-ai/sdk";

  const config = new Configuration({
    basePath: "https://openapi.beeos.ai",
    headers: { Authorization: `Bearer ${process.env.BEEOS_API_KEY}` },
  });

  const deploy = new DeployApi(config);
  const instances = new InstancesApi(config);
  const agents = new AgentsApi(config);
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "os"

      beeos "github.com/beeos-ai/sdk-go"
  )

  func main() {
      cfg := beeos.NewConfiguration()
      cfg.Servers = beeos.ServerConfigurations{
          {URL: "https://openapi.beeos.ai"},
      }
      cfg.DefaultHeader["Authorization"] = "Bearer " + os.Getenv("BEEOS_API_KEY")

      client := beeos.NewAPIClient(cfg)
      ctx := context.Background()
      _ = client
      _ = ctx
      fmt.Println("client ready")
  }
  ```

  ```python Python theme={null}
  import os
  import beeos

  configuration = beeos.Configuration(
      host="https://openapi.beeos.ai",
      access_token=os.environ["BEEOS_API_KEY"],
  )

  client = beeos.ApiClient(configuration)
  deploy = beeos.sdk.DeployApi(client)
  instances = beeos.sdk.InstancesApi(client)
  agents = beeos.sdk.AgentsApi(client)
  ```

  ```bash curl theme={null}
  export BEEOS_API_KEY="oag_…"
  export BASE=https://openapi.beeos.ai
  ```
</CodeGroup>

<Tip>
  Python users should install `beeos`, the stable official entry point. The
  complete generated OpenAPI surface remains available as `beeos.sdk`; see
  the [Python SDK guide](/sdks/python).
</Tip>

## 3. List the deploy catalog

<CodeGroup>
  ```typescript TypeScript theme={null}
  const providers = await deploy.listProviders();
  console.log(providers.data?.map(p => `${p.meta?.id} — ${p.meta?.name}`));

  const regions = await deploy.listDeployRegions({ providerId: "default" });
  const models = await deploy.listDeployModels({ agentFramework: "beeos-claw" });
  ```

  ```go Go theme={null}
  providers, _, _ := client.DeployAPI.ListProviders(ctx).Execute()
  for _, p := range providers.GetData() {
      fmt.Printf("%s — %s\n", p.Meta.GetId(), p.Meta.GetName())
  }
  ```

  ```bash curl theme={null}
  curl -s "$BASE/api/v1/providers" \
    -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'

  curl -s "$BASE/api/v1/deploy/regions?providerId=default" \
    -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'

  curl -s "$BASE/api/v1/deploy/models?agentFramework=beeos-claw" \
    -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'
  ```
</CodeGroup>

## 4. Deploy an agent instance

<CodeGroup>
  ```typescript TypeScript theme={null}
  const created = await instances.deployInstance({
    deployInstanceRequest: {
      name: "my-first-agent",
      agentFramework: "beeos-claw",
      modelPrimary: "gpt-4o",
    },
  });
  const instanceId = created.data!.id;
  console.log(`Instance ${instanceId} — status: ${created.data!.status}`);
  ```

  ```go Go theme={null}
  req := beeos.DeployInstanceRequest{
      Name:           "my-first-agent",
      AgentFramework: "beeos-claw",
      ModelPrimary:   "gpt-4o",
  }
  created, _, _ := client.InstancesAPI.DeployInstance(ctx).
      DeployInstanceRequest(req).Execute()
  fmt.Printf("Instance %s — status: %s\n", created.Data.GetId(), created.Data.GetStatus())
  ```

  ```bash curl theme={null}
  curl -s -X POST "$BASE/api/v1/instances" \
    -H "Authorization: Bearer $BEEOS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "my-first-agent",
      "agentFramework": "beeos-claw",
      "modelPrimary": "gpt-4o"
    }' | jq '.data'
  ```
</CodeGroup>

Provisioning takes a few seconds. Poll `GET /instances/{id}` until
`status === "running"`, or watch the dashboard.

## 5. Find the agent ID

A deployed instance hosts one or more agents. The agent ID is what you
invoke against (an instance can be replaced without breaking your
integration; the agent identity is stable).

<CodeGroup>
  ```typescript TypeScript theme={null}
  const list = await agents.listAgents({ instanceId, limit: 20 });
  const agentId = list.data![0].id;
  console.log(`Invoking agent ${agentId}`);
  ```

  ```go Go theme={null}
  list, _, _ := client.AgentsAPI.ListAgents(ctx).
      InstanceId(instanceId).Limit(20).Execute()
  agentID := list.GetData()[0].GetId()
  ```

  ```bash curl theme={null}
  AGENT_ID=$(curl -s "$BASE/api/v1/agents?instanceId=$INSTANCE_ID&limit=20" \
    -H "Authorization: Bearer $BEEOS_API_KEY" | jq -r '.data[0].id')
  echo "Invoking agent $AGENT_ID"
  ```
</CodeGroup>

## 6. Invoke the agent

The blocking call returns a single JSON payload once the agent finishes
its reply. For long prompts, see [Streaming](/guides/streaming).

<CodeGroup>
  ```typescript TypeScript theme={null}
  const reply = await agents.invokeAgent({
    agentId,
    invokeAgentRequest: {
      message: "Hello — what can you do?",
    },
  });
  console.log("Reply:", reply.data?.text);
  console.log("Channel:", reply.data?.context_id);
  ```

  ```go Go theme={null}
  reply, _, _ := client.AgentsAPI.InvokeAgent(ctx, agentID).
      InvokeAgentRequest(beeos.InvokeAgentRequest{
          Message: "Hello — what can you do?",
      }).Execute()
  fmt.Println("Reply:", reply.GetData().GetText())
  ```

  ```bash curl theme={null}
  curl -s -X POST "$BASE/api/v1/agents/$AGENT_ID/invoke" \
    -H "Authorization: Bearer $BEEOS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"message": "Hello — what can you do?"}' | jq '.data'
  ```
</CodeGroup>

### Streaming variant

Set `Accept: text/event-stream` on the same endpoint to receive
`agent_reply_delta` chunks followed by a single `agent_reply` close
frame. The SDK does not abstract SSE — drop to `fetch` / `http.Client`.

```bash theme={null}
curl -N -X POST "$BASE/api/v1/agents/$AGENT_ID/invoke" \
  -H "Authorization: Bearer $BEEOS_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"message": "Tell me a short story."}'
```

## 6.5. Where does the invoke show up?

Each `invoke` creates a short-lived `protocol=openapi` **task** channel,
not a conversation. List it with:

```bash theme={null}
curl -s "$BASE/api/v1/agents/$AGENT_ID/tasks?state=all" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq
```

`GET /agents/{agentId}/conversations` returns only long-lived dialog
channels you opened explicitly with `POST /conversations`. If that
list is empty right after an `invoke`, that is expected — see the
[calling agents](/guides/calling-agents) guide for when to pick
conversation vs invoke.

## 7. Clean up

```bash theme={null}
curl -s -X DELETE "$BASE/api/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq
```

## Where to go next

<CardGroup cols={2}>
  <Card title="Choosing a protocol" icon="signs-post" href="/guides/choosing-a-protocol">
    Decide between OpenAPI (this guide), A2A, and MCP.
  </Card>

  <Card title="Calling agents" icon="message-bot" href="/guides/calling-agents">
    Idempotency, attachments, tasks, conversations, error handling.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    HMAC-signed terminal-state callbacks with retry + audit log.
  </Card>

  <Card title="A2A protocol" icon="arrows-rotate" href="/a2a/overview">
    JSON-RPC + agent cards on `a2a.beeos.ai`.
  </Card>
</CardGroup>