Skip to main content

Agents

An agent is a system prompt, a chat model and, optionally, a knowledge base and tools. When someone talks to it, Orchestrate runs it as a durable workflow: it calls the model, runs any tools the model asks for, and records a trace of everything it did.

There are three ways to build one:

  • A single-step agent, made on the Agents page. This page covers it.
  • A workflow of several steps, with branches, parallel lanes and loops, made on the Workflows canvas. See Workflow graphs.
  • A code agent, written with a framework such as LangGraph, ADK or CrewAI and built by Orchestrate from your source. See Code agents.

Agents belong to a project. You need the developer or admin role on the project to create, change or run one.

Create an agent​

  1. Open Agents and choose New agent.
  2. Basics: enter a Name and an optional description. The name is how you call the agent from the API, so keep it stable. A name without spaces, such as support-triage, is easiest to use in an API path.
  3. Model: choose a chat model. Only models that are built and have a running deployment can be picked.
  4. Instructions: write the system prompt. Say what the agent should do, what it must never do, and what to do when it cannot answer.
  5. Knowledge: optionally pick one knowledge base the agent can search. See Knowledge bases.
  6. Tools: optionally pick connector tools the agent may call, or other agents of the project. See Tools and connectors and Agents calling agents.
  7. Choose Create agent.
tip

The model list also offers Default (external provider). An agent with this choice sends its calls to an external provider, and fails on an install that has none. On an air-gapped install, always pick a model.

Orchestrate adds the current date and time to the end of every agent's system prompt, so the agent can answer "what day is it" and "next Monday" questions. The time is in the organization's time zone, set under Organizations > Settings. Without one, the install's agentTimezone applies, and Asia/Dubai when that is empty too.

Versions​

Every save creates a new version. Open an agent and choose Edit: the save button reads Save as v2, Save as v3 and so on. Older versions are kept. Choose Duplicate to start a new agent from an existing one.

The Agents page edits single-step agents. An agent with several steps is edited on the Workflows canvas. See Workflow graphs.

Each agent has one live version. A call to the agent by name runs the live version. By default, saving makes the new version live straight away. A project admin can change this so that saves create drafts, or so that a version must pass its evals before it goes live. See Live versions and the release gate.

Test it​

Choose Test on the agent, or Open in Playground in its details panel. Every Playground turn is a real run, with the agent's real prompt, tools and knowledge base. See Playground.

How a run works​

  1. The agent's system prompt, the conversation so far and the new message go to the model through the Model Gateway.
  2. If the model answers, the run ends with that answer.
  3. If the model asks for tools, Orchestrate checks whether each call needs approval, runs it, and sends the result back to the model. See Human approval.
  4. This repeats until the model answers. After five model calls without a final answer, the step stops with the message Max tool iterations reached without a final answer. A workflow step can raise or lower that number. See Model settings.

If the model returns an empty answer, Orchestrate asks it once more, then fails the step and says so, rather than return nothing.

Every run is recorded with its steps and tool calls. See Runs and traces.

Some small models write a tool call out as text instead of returning it in the structured format. Orchestrate recognises the common <tool_call> format and runs the call, and the trace marks it. If a model's tool calls cannot be read, the run says so instead of returning the raw markup. If a model sends tool arguments that are not valid JSON, the tool is not run. The model is told and can try again, and the trace marks the call as failed.

Conversation memory​

Each agent version has a Memory setting: how much of a conversation its model is sent on each turn, and what happens to the rest. Set it in the agent editor's Memory section, or in a workflow's inspector.

ModeWhat the model is sent
Whole conversation (default)Every earlier turn. A long conversation gets slower and costs more with every turn.
Recent turns onlyThe newest turns that fit the History budget, in estimated tokens. Older ones are left out.
Recent turns and a summaryThe newest turns that fit, word for word, and a running summary of the older ones that a model writes.
No memoryEach message on its own.

With a budget you also set the Recent turns kept, and with a summary its Summary size and the Summary model (the agent's own model by default). Summary calls are billed to the agent. If a summary call fails, the older turns are left out for that turn instead of failing the run.

On API and chat threads the summary is kept with the thread, redacted like its turns, and deleted with it, so the next run gets the summary and only the newer turns. Voice calls don't wait for a summary: they keep recent turns only.

A new version that leaves memory unset keeps the setting of the newest version.

Run an agent from your code​

Applications call agents through the Agent API with a project API key: OpenAI-compatible chat completions, threads that Orchestrate keeps, and async runs with webhooks. That is the way to use for an integration.

To run an agent on a schedule, or when another system posts to a webhook, see Schedules and webhooks.

Scripts that act as a person can also call the agent by name with a Keycloak access token. The live version runs. If the name has spaces, URL-encode it in the path.

curl -X POST "$ORCHESTRATE_API/agents/support-triage/run" \
-H "Authorization: Bearer $ORCHESTRATE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "project_id": "default", "input": "My invoice shows the wrong address." }'

For a conversation, send the whole transcript to /agents/{name}/chat instead, ending with the user's new message. Orchestrate does not keep the conversation for you between calls.

The API waits up to two minutes for the answer. The response says what happened:

statusMeaning
completedThe run finished. The answer is in result.final, and result.trace lists each step's tool calls.
awaiting_approvalThe run is waiting for a person to approve a tool call. pending_approvals lists them.
rejectedA person rejected a tool call, or nobody approved it in time, so the run stopped.
runningThe run is still working after two minutes. Follow it with the workflow_id.

A run keeps going after the API stops waiting. Read it later with GET /workflow-runs/{workflow_id}.

note

These routes need a Keycloak access token for a project member. A personal API key (vcpk_) is for the Model Gateway only. Applications use a project API key (vcpj_) on the Agent API. See API authentication.

See the Agents API for every field.

Agents with more than one step​

An agent can have several steps, each with its own system prompt, model and tools. A step can take the output of an earlier step as its input with input_from. Only the first step sees the conversation history. Build them on the Workflows canvas, with branches, parallel lanes and loops, or through the API. See Workflow graphs.

On a voice call, a multi-step agent runs every step on each turn. See Voice agents.

Delete a version​

Deleting a draft changes nothing else. Deleting the live version:

  • makes the newest remaining version live, when saves go live in this project
  • is refused, when the project saves drafts or requires passing evals. Make another version live first.
  • removes the agent's live version, when it is the agent's last version
Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →