# Agent Runtime

> **Private beta**
>
> Agent Runtime is in private beta. If the API answers 404 for every agent route, your account is not in it yet: write to contact@orkestr.eu.

An agent is a model, a system prompt, tools and skills, published as a version. Your app calls it over the API. Every conversation (a session) runs in its own small VM in the EU, and orkestr does not store the conversation: it lives in that VM until the session ends.

## What an agent is made of

- **Model**: your own provider key (a model credential), added once in the console. Mistral, OpenAI, or any OpenAI-compatible endpoint. The key never enters the VM.
- **System prompt** and **skills**: playbooks the agent loads on demand (`slug`, `description`, `body`), up to 20.
- **Tools**: the built-in ones below, plus your own MCP servers and HTTP APIs ([toolsets](https://orkestr.eu/docs/agents/tools)).
- **Settings**: `max_steps` (model calls per run, 1 to 50), `size` (small, medium, large), `network` (`restricted` by default, `open` on pay as you go), `allow_domains`, `memory_enabled`.

## Built-in tools

Always on, and they run inside the session VM:

- `run_code`: Python 3; variables persist between calls in a run.
- `run_shell`: a bash command; returns output and exit code.
- `read_file`, `write_file`, `list_files`: the workspace, kept for the whole session.
- `web_fetch`: a URL as text, limited to the hosts the agent may reach.

## Versions and endpoints

Every change publishes a new, immutable version. An endpoint (alias) points at one version; `prod` is the default an invoke runs. Promoting and rolling back are the same move: point the alias somewhere else. A new session uses the version its alias points at when it starts; a live session stays on its version.

```bash
orkestr agents publish my-agent --prompt-file prompt.md --notes "tighter answers"
orkestr agents promote my-agent prod 3     # roll back to v3
```

## Sessions

The first invoke creates a session and returns its `session_id`. Pass it back to continue the conversation. Between messages the VM sleeps (parks) and wakes in about a second. Ending a session destroys its VM and with it the conversation; later invokes on it get `410 session_ended`.

## Next

- [Quickstart](https://orkestr.eu/docs/agents/quickstart): create one and call it from code.
- [Tools and approvals](https://orkestr.eu/docs/agents/tools)
- [Memory and end users](https://orkestr.eu/docs/agents/memory)
- [Schedules and webhooks](https://orkestr.eu/docs/agents/triggers)
- [REST API reference](https://orkestr.eu/docs/agents/api-reference)