NOLGIANOLGIADocs

Agent

The NOLGIA Agent

On this page
  1. A turn, not a request
  2. What it can do
  3. Where it runs
  4. Run your first turn

A model API call makes one thing: you pick the model, write the prompt, submit the job and collect the file. The NOLGIA Agent does the picking. You describe what you want, and it plans the work, chooses the models, writes the prompts, submits the generations, looks at what came back, and keeps going until the work is done or it needs an answer from you.

A conversation with the NOLGIA Agent and the Outputs it creates
A conversation with the NOLGIA Agent and the Outputs it creates

Everything it makes lands in the same Library as work you generate yourself, under the same credits, the same organization context and the same file access rules. It is another way into the platform, not a separate one.

A turn, not a request #

One agent turn Your app creates an agent session, then posts a message to start a turn. The NOLGIA Agent runs the turn while the events endpoint streams steps and assets back to your app. While the turn runs your app may steer it with another message or interrupt it. The turn ends with a reply message and credits are charged per turn. Your app Agent Sessions API NOLGIA Agent POST /agent/sessions POST /agent/messages GET /agent/sessions/{id}/events streams steps and assets optional while the turn runs steer: another message while running POST /agent/sessions/ {id}/interrupt session created turn starts reply message credits per turn runs the turn: steps, tools, assets
An agent turn: message, events stream, optional steer or interrupt, reply

One message and everything the agent does to answer it is a turn. A turn can run for many minutes and submit many generations; it is asynchronous from the start, so you submit a message and then follow it rather than holding a request open. While it runs you can stream its steps, steer it with another message, or stop it.

Turns live in sessions. A session keeps its transcript and the media its turns produced together, so a conversation can be resumed and its Outputs collected later. The Agent Sessions API is the full contract: sessions, messages, streaming, steering, interrupts, assets and errors.

What it can do #

The agent's skills are abilities: installed packages that teach it a job, from product photography to long-form video. Every agent is provisioned with a core set and you can install more from the marketplace, pin one to a version, and see what is installed. See Abilities.

It reaches the platform with its own credential, so the work it does is attributed to it, and GET /agent/usage reports what it spent on your behalf.

Where it runs #

Each account gets one agent of its own, with its own configuration and its own long-term memory, separate from every other account's. You provision it, configure the environment it runs with, read its desired state, and take it down again. See The operator model.

Run your first turn #

Provision the agent once, create a session, send a message, then poll the reply until it leaves pending.

shell
curl -sS -X POST https://api.nolgia.ai/v1/agent \
  -H "Authorization: Bearer $NOLGIA_TOKEN"
curl -sS https://api.nolgia.ai/v1/agent/sessions \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"First session"}'
export SESSION_ID=<id from the response>
curl -sS https://api.nolgia.ai/v1/agent/messages \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"session_id\":\"$SESSION_ID\",\"content\":\"Make me a 5 second clip of a paper boat on a puddle.\"}"
export MESSAGE_ID=<agent_message_id from the response>
curl -sS "https://api.nolgia.ai/v1/agent/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

Provisioning is asynchronous: POST /agent answers 201 immediately, and the agent reports chat_connected once it is reachable. A turn sent before that point does not wait for it, so read GET /agent first: the reply comes back failed, saying the chat endpoint is not connected yet.

When the reply reaches complete, read its content, and collect what the turn made with GET /agent/sessions/{id}/assets.