Skip to documentation
eli.aidocs

Ports

Creating agents

An agent is a named, versioned configuration over the shared harness. You define which model it uses, which tools it may call, what slice of the KB it can see, and the hard budgets and guardrails it runs under. Manage agents at /w/<workspace>/agents. The runtime is described in Agents & the harness.

Create an agent

  1. Name it

    Give the agent a name and description. The name is slugified (lowercase, dashes) into the slug used in URLs and the API — e.g. "Budget Analyst" → budget-analyst.

  2. Choose a model slot

    Pick agent (the default, top-tier) or chat. The slot resolves to whatever provider/model your workspace has bound to it — the agent config doesn't hard-code a model, so swapping providers is a one-line change. See Multi-provider AI.

  3. Pick tools

    Select from the allowlist. The default is all five read-only KB tools: kb_search, kb_doc_read, kb_list_docs, kb_entity_lookup, kb_graph_query. Enabled MCP tools (named mcp:<server>:<tool>) can be added; they require approval on every call.

  4. Scope the KB (optional)

    Restrict what this agent can read with kbScope: folders, tags, and/or entityTypes. Scope is injected into every tool call by the registry — the model can't widen it.

  5. Set budgets & guardrails

    Configure per-run budgets and whether citations are required, then save.

The config shape

A config is validated (and clamped) on every write. Budgets can never exceed the env-level ceilings (MAX_AGENT_STEPS, MAX_AGENT_COST_USD).

agent version configjson
{
  "runtimeTier": "portable",
  "modelSlot": "agent",
  "systemPrompt": "You are a budget analyst for Northwind…",
  "tools": ["kb_search", "kb_graph_query", "kb_doc_read"],
  "kbScope": {
    "folders": ["northwind/finance"],
    "tags": ["budget"],
    "entityTypes": ["Organization", "Project"]
  },
  "budgets": {
    "maxSteps": 12,
    "maxTokens": 200000,
    "maxCostUsd": 1,
    "maxWallClockMs": 180000
  },
  "guardrails": { "citations": { "required": true } }
}

Budgets & guardrails, explained

  • maxSteps — model-call iterations before a graceful stop.
  • maxTokens / maxCostUsd — token and dollar ceilings; every harness call (retries, judge) draws them down, so the cap is real.
  • maxWallClockMs — wall-clock limit (default 180s).
  • guardrails.citations.required — when true, an answer without valid citations is retried and then blocked. The groundedness judge always runs but only flags.

Immutable versions

Every save publishes a new immutable agent_version (v1, v2, …). Runs pin the version they used, so an eval regression compares like-for-like and every improvement is attributable to a specific config. You never mutate a version — you publish a new one.

Ownership

Editing an agent config is an owner-gated action in workspaces that require it. Versions are append-only — history is preserved for audit and A/B comparison.

Run it

Start a run from the agent's page, from the run view, or programmatically via POST /api/v1/agents/:slug/runs. Schedule recurring runs in Cost & schedules.

Endpoints

  • GET/POST /api/w/:workspaceId/agents — list / create.
  • GET /api/w/:workspaceId/agents/:slug — the agent with its latest version.
  • POST /api/w/:workspaceId/agents/:slug/versions — publish a new version.