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; live data (kb_data), structured records (kb_records), assets & skills (kb_assets) and write-via-approval (kb_propose_note) are opt-in. Enabled MCP tools (named mcp:<server>:<tool>) can be added; they require approval on every call.

  4. Lock its capabilities (optional)

    Set a capabilityLock — the combination of platform capabilities this agent may ever touch: documents, graph, governance, data, records, assets, memory, external. A locked agent cannot be published, run, or mounted outside its lock. No selection means unlocked.

  5. 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.

  6. 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"],
  "capabilityLock": ["documents", "graph"],
  "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.

The capability lock

The lock binds an agent to a combination of platform capabilities, and it is enforced three independent times, so no single mistake can widen an agent's reach:

  • At publish — a version whose tools or flags reach outside its own lock is rejected with every violation named. A misconfigured agent cannot be saved, not merely not-run.
  • At run time — the runner re-filters the assembled toolset through the lock, so a lock added after older versions were published still binds their runs.
  • On the MCP mount — /api/mcp/agents/:slug registers only the tools the lock exposes. A locked-out tool is not listed, not merely denied.

The lock never widensauthorization: every call still runs the caller's API-key scopes, the live user's role capabilities, and the content ACL. It is a ceiling on the agent, intersected with the caller's own permissions.

Serve it over MCP — self-service harnesses

Every agent is also an MCP server: mount /api/mcp/agents/:slugin Claude, an IDE, or your own chatbot harness and the client sees exactly the locked toolset — the same tools the agent's own runs use, resolved against the latest published version on every request. Publishing a new version retunes every mounted client without a remount. The in-app chat tab on the agent's page is the same harness pattern over the durable runner: locked tools, HITL checkpoints, citations and audit included.

mount one locked agentbash
claude mcp add --transport http eli-docs-desk \
  https://eli.ai/api/mcp/agents/docs-desk \
  --header "Authorization: Bearer eli_sk_..."

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 (in-app).
  • GET /api/w/:workspaceId/agents/:slug — the agent with its latest version.
  • POST /api/w/:workspaceId/agents/:slug/versions — publish a new version.
  • GET/POST /api/v1/agents, GET /api/v1/agents/:slug, POST /api/v1/agents/:slug/versions — the same builder surface for API keys (see the API reference, tag “Agent builder”).
  • /api/mcp/agents/:slug — the agent-scoped MCP mount.