Skip to content

Make an assistant#

An assistant is what a person chats with: instructions (who it is, its rules, what it should know of your workspace), the deployment it thinks with, and its tools — web search, reading pages, the code interpreter, knowledge bases, memory, Astralyx tools. A deployment is the bare model; an assistant is what you make of it. Several assistants can share one deployment: a trip planner and a cluster helper on the same model, each with its own instructions and tools.

An assistant is chatted with in the app, on Telegram, in the Playground and through the OpenAI-compatible API as assistant/<name>; it can be shared with people outside the workspace.

Before you begin#

  • A chat deployment in the workspace (Create and manage deployments).
  • The permission assistants:create (the roles Developer and ML engineer – serving have it; Analyst may chat with assistants, assistants:call).

Create one#

  1. Open Eos → Assistants and press New assistant.
  2. Name: lowercase letters, digits and - — how the app, the Playground and the API name it.
  3. Thinks with: a chat deployment of the workspace.
  4. What it is for: a sentence (at most 300 characters), shown where it is chosen.
  5. Instructions: Markdown, at most 32,000 characters. They go before every conversation, before the caller's own system message: keep what it needs each time, and put long material in a knowledge base.
  6. Plan requests of several steps (on for a new one): the model keeps a plan you see.
  7. Press Make assistant.

Beside the form, Try it is a chat with the assistant as written there, before you save: change the instructions and ask again. Its memory is read only there — a test keeps no facts. A deployment's page makes one too: Assistants → Make an assistant with this model.

With no assistant yet, the app offers Make my assistant: a name, a model, a kind (Personal assistant, Study partner, Coding assistant, or Blank) with instructions to start from, and what it may use — Search the web, Read links and documents, Calculate and run code, Remember me, Use the workspace's documents, Plan requests of several steps — each on when your workspace has it, or saying what to install.

Below, <org>/<workspace> and <cluster> are yours, and ast_pat_… a personal access token.

curl -X POST "https://console.astralyx.cloud/api/v1/orgs/<org>/workspaces/<workspace>/clusters/<cluster>/api/assistants" \
  -H "Authorization: Bearer ast_pat_…" -H "Content-Type: application/json" \
  -d '{"metadata": {"name": "travel"},
       "spec": {"deployment": "chat",
                "description": "Plans trips",
                "instructions": "You are the travel assistant. Answer in Portuguese; prices in reais, each with where it comes from.",
                "plan": true}}'

spec.deployment is a deployment of the same workspace (another workspace's is refused: INVALID_ASSISTANT). PUT …/assistants/<name> with {"spec": …} changes it, DELETE removes it.

Its tools#

On its page, Tools gives it the workspace's functions (web search, read a page, those you wrote), the code interpreter, knowledge bases and memory, and Astralyx tools — for this assistant alone: its deployment and the deployment's other assistants are not changed.

In the API: spec.tools, spec.tool_limits and spec.astralyx take the values Give a model tools describes.

To try other tools or instructions without changing it, use the Playground's Harness: Save to keeps what you tried.

A visible plan#

With Plan requests of several steps (spec.plan: true) the model is given update_plan: for a request of several steps it lists them first and calls it again as it goes — one step in progress at a time, then done. The chat shows the latest list as a checklist (Plan · 2 of 4 done) instead of a tool card. Nothing runs: it only shows the steps. A deployment can list the same tool among its own ("update_plan" in spec.tools).

Chat with it#

  • App: the picker lists the workspace's assistants and those shared with you; you chat with assistants there (bare models are the Playground's and the API's).
  • Telegram: connect it once, then write to it there.
  • Playground: they come first among the targets.

What it can do — images, tools, reasoning, its context — is its deployment's. A chat with an assistant keeps everything a deployment's chat does: answers kept when you leave (what passes where), Compact, its memory.

Call it with an API key#

Through the hosted gateway, an API key of the workspace calls an assistant as assistant/<name>, on POST /v1/chat/completions (streamed or whole); GET /v1/models lists the assistants the key may call:

# <hosted-gateway>: the address Eos → API keys shows for the hosted gateway
curl https://<hosted-gateway>/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" -H "Content-Type: application/json" \
  -d '{"model": "assistant/travel", "messages": [{"role": "user", "content": "Which documents do I need?"}]}'

The key must be allowed to call the assistant's deployment, and the deployment must allow the hosted gateway; the tokens are counted under the key. The gateway on your edge machines does not call assistants yet: it answers model_not_found saying so — call the deployment by name there.

Share it#

On its page, Shared with invites someone by e-mail to chat with it (or only to see it). Once they accept, it is in their app's picker as · shared by . They reach this assistant and nothing else of the workspace — not its deployment, its tools' settings, the models, the machines — and it has none of its Astralyx tools for them. Their memory is their own: they never read yours or the workspace's (Memory per person). Take back ends it; their chats stay on their devices.

Its maker and the workspace's admins share it. A guest's access is checked by the cluster on every request, not only by the console.