# Quickstart

Create an agent, then call it from your code.

## 1. Create an agent

1. In the console, open **Agents** and add a model credential (your provider key).
2. Create the agent: a name, a system prompt, the model. Its config becomes version 1 and the `prod` endpoint points at it.
3. Try it on the agent's **Test** tab.
4. Create an API token with the `agents:invoke` scope and set it as `ORKESTR_API_KEY`.

Or from the CLI (the model credential still comes from the console):

```bash
pip install --upgrade orkestr-cli && orkestr login
orkestr agents credentials                       # your model keys (never shown)
orkestr agents create analyst --prompt-file prompt.md --memory
orkestr agents run analyst "Summarise this week's signups"
```

Or from code, with a token that has `agents:write`:

**Python:**

```python
from orkestr import Agent, ModelCredential

cred = ModelCredential.list()[0]           # added once in the console
agent = Agent.create("analyst", {
    "system_prompt": "You analyse product data and answer in short bullets.",
    "model_credential_id": cred["id"],
    "memory_enabled": True,
}, description="Weekly numbers")           # config = version 1, served at prod
```

**JavaScript:**

```javascript
import { Agent, ModelCredential } from "orkestr";

const [cred] = await ModelCredential.list();   // added once in the console
const agent = await Agent.create("analyst", {
  system_prompt: "You analyse product data and answer in short bullets.",
  model_credential_id: cred.id,
  memory_enabled: true,
}, { description: "Weekly numbers" });          // config = version 1, served at prod
```

## 2. Call it

**Python:**

```python
pip install orkestr
```

**JavaScript:**

```javascript
npm install orkestr
```

**Python:**

```python
from orkestr import Agent   # reads ORKESTR_API_KEY

agent = Agent.get("analyst")             # name or agt_ id
result = agent.invoke("Summarise this week's signups")
print(result.status, result.output)      # completed ...

# Continue the same conversation:
agent.invoke("Which day was busiest?", session_id=result.session_id)
```

**JavaScript:**

```javascript
import { Agent } from "orkestr";   // reads ORKESTR_API_KEY

const agent = await Agent.get("analyst");
const result = await agent.invoke("Summarise this week's signups");
console.log(result.status, result.output);

// Continue the same conversation:
await agent.invoke("Which day was busiest?", { sessionId: result.sessionId });
```

**cURL:**

```bash
curl -X POST https://api.orkestr.eu/v1/agents/analyst/invoke \
  -H "Authorization: Bearer $ORKESTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Summarise this week'\''s signups", "wait_s": 30}'
# 200 {"run_id": "run_...", "session_id": "ses_...", "status": "completed", "output": "..."}
# 202 if it is still running after wait_s: poll GET /v1/agents/runs/{run_id}
```

Pass `end_user_id` (`endUserId` in JavaScript) when you serve your own users: it scopes memory, usage and erasure per user. `qualifier` picks a version for a new session (an alias, `v3` or `latest`).

## 3. Stream it

Events arrive as Server-Sent Events: `run.accepted` first (with `run_id` and `session_id`), then `tool.call` / `tool.result`, and finally `run.completed`, `run.failed` or `run.paused` (waiting for an approval). Every event has an id; reconnect to `GET /v1/agents/runs/{run_id}/stream` with `Last-Event-ID` to resume a dropped stream.

**Python:**

```python
for event in agent.stream("Summarise this week's signups"):
    if event.type == "tool.call":
        print("->", event.data["name"])
    elif event.type == "run.completed":
        print(event.data["output"])
```

**JavaScript:**

```javascript
for await (const event of agent.stream("Summarise this week's signups")) {
  if (event.type === "tool.call") console.log("->", event.data.name);
  if (event.type === "run.completed") console.log(event.data.output);
}
```

**cURL:**

```bash
curl -N -X POST https://api.orkestr.eu/v1/agents/analyst/invoke \
  -H "Authorization: Bearer $ORKESTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Summarise this week'\''s signups", "stream": true}'
```

## Or let your coding assistant build it

Paste this into Claude Code, Codex, Cursor or any agent that runs shell commands. It installs the CLI, logs you in through the browser, and builds and tests the agent:

```bash
curl https://orkestr.eu/agents.md and build an orkestr agent that <does what, for whom>
```

> The assistant never sees your model key or tool keys: those are added in the console, or passed to the CLI by environment variable name.