Prime: the harness

What Prime, AGNT's agent harness, does on every chat turn and task, how chats and tasks reach it, how it uses each user's memory, and how model tiers are chosen.

Prime is AGNT's agent harness: the runtime that executes every chat turn and every task, for every user, in every app built on AGNT. You do not write an agent loop, a tool router or a retry policy. You create chats and tasks, and Prime does the work. Your end users never see Prime: they talk to the assistant your app names and brands, such as Harborview's Ava.

How it works

Each behavior below holds for every run, with no configuration.

Chats and tasks

Your app reaches Prime through two resources. A chat is a conversation: the user writes, the assistant answers. A task is a job with an outcome, such as "Renew the Brightline Freight service contract", that runs until it is done.

 user message
      |
      v
 +--------------------+     quick answer     +----------------------+
 | Chat turn          |--------------------->| reply in the chat    |
 | (chat process      |                      +----------------------+
 |  call)             |     real work        +----------------------+
 +--------------------+--------------------->| Task (durable)       |
                                             |   runs, waits, wakes,|
 your backend -- POST /tasks --------------->|   asks for approval  |
              -- POST /tasks/:id/process --->|                      |
                                             +----------------------+

When Prime opens a task from a chat turn, the turn's message event includes the new taskIds. Both resources belong to a user: send X-User-Email with an account API key, or use a user key. See Authentication.

• Assistants and messaging covers creating chats, sending messages and reading the event stream.
• Tasks, autonomy and approvals covers creating, running and following tasks.
• The Quickstart runs a first task end to end.

Memory

Memories are short facts Prime keeps about a user: preferences, important dates, people and standing instructions. Prime reads them on every run and writes new ones as it learns. Your app reads and writes the same store, for example to import what you already know about a user at sign-up.

Create a memory

Save how Jane wants vendor quotes presented:

curl https://api.agnt.ai/memories \
  -X POST \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Jane prefers vendor quotes summarized in a table with price, lead time and warranty.",
    "tags": ["general"]
  }'

{
  "ok": true,
  "memory": {
    "id": "6702c7f3a4b5c6d7e8f9a0b1",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "user": "6702b1e8f9a0b1c2d3e4f5a6",
    "kind": "unstructured",
    "content": "Jane prefers vendor quotes summarized in a table with price, lead time and warranty.",
    "tags": ["general"],
    "source": "user",
    "scope": "user",
    "team": null,
    "startDate": null,
    "endDate": null,
    "isActive": true,
    "isExpired": false,
    "pinned": false,
    "metadata": {},
    "createdAt": "2026-11-02T16:24:11.000Z",
    "updatedAt": "2026-11-02T16:24:11.000Z"
  }
}

Tie a memory to a person with a contact: tag, and to a date with date-memory:

curl https://api.agnt.ai/memories \
  -X POST \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Always loop in Maria Chen on board meeting prep.",
    "tags": ["contact:[email protected]"]
  }'

curl https://api.agnt.ai/memories \
  -X POST \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Dana Okafor at Brightline Freight handles contract renewals and wants redlines as PDF.",
    "tags": ["contact:[email protected]"]
  }'

curl https://api.agnt.ai/memories \
  -X POST \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Board meeting week. Keep Jane'\''s calendar clear for Q1 2027 board meeting prep.",
    "tags": ["date-memory", "title:Board meeting week"],
    "startDate": "2026-11-16T00:00:00.000Z",
    "endDate": "2026-11-18T23:59:59.000Z"
  }'

The same calls in the TypeScript SDK:

const jane = client.as('[email protected]');

await jane.memories.create({
  content: 'Always loop in Maria Chen on board meeting prep.',
  tags: ['contact:[email protected]'],
});

The SDK also has memories.list, get, update and delete. See Authentication for SDK credentials.

Tags

A tag outside this vocabulary returns 400 with a message listing the accepted tags.

List memories

List everything Jane's assistant knows about Maria:

curl "https://api.agnt.ai/[email protected]&perPage=50" \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "X-User-Email: [email protected]"

Results are newest first, in { "ok": true, "memories": [], "page", "perPage", "total" }.

Visibility

A user sees their own memories and the team-scoped memories of teams they are an active member of. Nothing else crosses users. Only a memory's author can update or delete it. Notes Prime keeps for its own operation are not returned by the API.

Model tiers

Every run uses one of four tiers: low, medium, high or ultra. Your code chooses tiers, never model ids. Which model serves each tier is set per account on the console's Models page (Model Strategies), so you change models without a code change. The console labels medium as Standard.

Prime is model-agnostic: each model tier can be served by models from several providers, including open-weight models, and you change this without a code change.

Each chat and task has its own modelTier, fixed when it is created. A chat or task your app creates through the API uses the first of these that is set:

1. The modelTier you pass to POST /tasks or POST /chats.
2. The organization's default, set with PATCH /organizations/:orgId/settings/model-tiers.
3. The account's default, set in the console under Settings → Model.
4. medium.

Chats and tasks that Prime creates on its own, for an inbound message or a task opened from a chat, check a matching segment's default first, then the organization, the account and medium. A segment is a named set of your organizations, teams or users, defined on the console's Segments page, with its own default tiers and model strategies. Use one to route a single customer to stronger models without changing anyone else's.

Chats and tasks have separate defaults. A tier value outside the four returns 400. Users, organizations and teams shows how to set an organization's defaults.

Extend Prime

• Skills package what Prime can use: instructions and knowledge, agents and prompts, CLI tools, plugins, workflows and MCP servers. Installed skills are available to the user's runs, and POST /tasks takes a skills list for one task. Manage skills with the CLI or in the console. Workflows, skills that start tasks on a schedule or an event, are covered in Tasks, autonomy and approvals.
• MCP servers are skills of kind mcp, created with POST /skills. mcpServerUrl is required. mcpTransport (streamable-http or sse) and mcpAuthType (none, oauth or api_key) are optional, and name, title and description come from the server when you omit them. Prime discovers the server's tools and calls them alongside its own.
• Plugins run sandboxed, with no access to platform secrets or other tenants' data.

MCP servers and the workspace are off under the restricted security preset. See Security.

Depend on the API's statuses, events and fields, not on the wording of the assistant's replies. Nothing an end user sees refers to Prime or AGNT unless you put it there.

Endpoints

See also

• Quickstart: a first task end to end
• Tasks, autonomy and approvals: durable work and human approval
• Assistants and messaging: assistants, channels and the chats API
• Security: isolation and untrusted content