API & usage

This page is about calling agent-core, not authoring it. Three audiences reach the package through three distinct surfaces:

• a model calls agent-core's native tools;
• a client (the chat UI, a skill script, an external MCP client) calls its HTTP routes, each gated by a feature the caller must hold;
• another package calls it in-process through the typed getPackageApi() adapter — never over MCP.

For contributing tools, routes, skills, or UI to agent-core, start at the package overview and the directory contract instead.

1. The model-facing toolsCopy Anchor Link

agent-core ships its native tools as tools/*.json schemas. Each is loaded, AJV-validated, and dispatched through the same policy, feature-gate, and approval machinery as any package's tools (see tools for the deep dive on the complete catalog). A model calls a tool by name with arguments matching its schema; below are representative calls and their typical result shapes.

execute — run a sandboxed shell command or activate a skillCopy Anchor Link

{ "action": "shell", "command": "ls data://notes", "reason": "list the notes folder" }

Result: a card with stdout, stderr, exitCode, and the resolved working directory. action: "skill" instead renders a SKILL.md body into context and stages its declared credentials for later shell calls.

delegate — spawn a subagent with its own full agentic loopCopy Anchor Link

{ "task": "Audit the auth routes for missing feature gates", "max_steps": 20 }

Result: the child's final summary text, plus a persisted child transcript openable read-only from the chat UI. The child inherits the conversation's permission profile.

workflow — create and manage scheduled workflows (the Calendar)Copy Anchor Link

{ "action": "schedule", "title": "Daily digest", "instruction": "Summarize new issues", "cron": "0 9 * * 1-5", "timezone": "Europe/Budapest" }

Result: the created/updated WorkflowEntry, a list, or a run's event log depending on action. Requires workflow.read, escalating to workflow.write / workflow.dispatch per action.

web_search — search the public webCopy Anchor Link

{ "query": "MCP stateless transport RC", "mode": "research", "max_results": 8 }

Result: a ranked list, each entry carrying at least { title, url, publishedAt, snippet } (plus content_markdown in research mode with include_content); publishedAt is a normalized YYYY-MM-DD day, absent when no date could be determined. provider picks the strategy — auto (default), native, tavily, brave, searxng — and every one falls back to a keyless engine rather than failing. Gated by core.web. Native search runs on the conversation's own model, so its tokens and the vendor's per-search fee are recorded in the same usage event as the rest of the turn and count against the project's spend limits.

web_fetch — fetch and extract readable content from one URLCopy Anchor Link

{ "url": "https://example.com/article", "max_chars": 20000, "format": "markdown" }

Result: the page's content, up to max_chars, fetched through the hardened DNS-pinned, private-IP-blocking pipeline. HTML, Markdown, JSON, XML, plain text and PDF are all handled. format selects the rendering (markdown, text, raw, json); save_to ("tmp" or a data://… path) stores the result and additionally requires drive.write — with core.execute on top for "tmp", which is the shell substrate's own private scratch directory. Gated by core.web.

ask_question — pause and ask the user explicit questionsCopy Anchor Link

{ "question": "Which environment should I deploy to?", "options": [{ "id": "stg", "label": "Staging" }, { "id": "prod", "label": "Production" }] }

Result: the stream blocks until the user answers; the answer(s) return to the model. Use only when the decision genuinely belongs to the user.

todos — maintain the session working-stateCopy Anchor Link

{ "plan": { "name": "Refactor", "todos": [{ "id": "schema", "content": "Tighten the tool schema", "status": "in_progress" }] } }

The same plan key also formalizes the session goal and loop bound — in the same call or a later one. The goal records the outcome and acceptance evidence; todos remain the executable steps:

{ "plan": { "goal": "Tighten every tool schema", "done": ["all tools validate", "docs updated"], "loop": { "until": "goal", "maxSteps": 40 } } }

Later, mark satisfied acceptance conditions without resending the locked goal — by the number the prompt lists them under (- [ ] 1. all tools validate) or by their exact text, all-or-nothing, together with any todo progress:

{ "mark": { "met": [1] } }
{ "mark": { "todos": [{ "id": "schema", "status": "completed" }], "met": [2] } }

Without close, keys sent together apply plan, then mark, whatever order they arrive in, and a locked goal fails the whole call before anything is written. With close, mark and close end the current cycle first and plan opens the next, so one call replaces a goal the agent set itself (when nothing is open, the close is skipped and named):

{ "close": "cleared", "plan": { "goal": "Tighten the tool schemas the audit named", "done": ["audit list validates"] } }

A refused step stops the call, and the answer names what already landed. Result: the updated goal, loop and todo list, re-rendered into the system prompt inside one <session> block. The working-state is durable — it persists with the conversation, survives a restart, and is shared across a multi-user conversation. A goal/loop is free to set once per cycle, then LOCKS: mark.met can only flip existing conditions to met, until is locked once set, and maxSteps can only be lowered (and is enforced); the user changes the rest. An explicitly authored self-evolving run (evolve: "agent") is the sole goal-rewrite exception; it still cannot loosen the loop bound. plan.loop's maxSteps folds into the run's step ceiling.

The cycle closes by itself. The tick that meets the last condition (or { "close": "achieved" } on a fully-met or condition-less goal) archives the goal and the current todo list as one versioned entry in the conversation's meta.json (sessionLedger.history[], bounded by the sessionArchiveMaxEntries platform setting), empties both, and answers archived as v<n>; the prompt then carries one Archived: v<n> "…" achieved (3/3 · 5/5 todos) line. A todo list with no goal (or a goal without conditions) closes the same way when every step is completed. { "close": "cleared" } archives an obsolete goal the agent authored itself as cleared (with no goal open, its own todo list); a goal set by the user or a workflow is theirs — the agent can achieve it, never drop it (the prompt marks it [set by user — locked]), except in a self-evolving run, where the marker drops locked and the agent may clear the goal too. The composer's Goal & loop dialog offers the same Achieve / Clear to the user and lists the archived cycles; a workflow's seeded goal re-asserts itself on the next fire after a close.

compact_history — free context-window spaceCopy Anchor Link

{ "actions": [{ "target": { "tool_use_id": "toolu_abc" }, "action": "remove" }], "reason": "context filling" }

Result: an in-place, reversible, non-destructive trim of earlier context. Reference a tool output by its tool_use_id (the ⟦id⟧ handle shown in the conversation map) or a whole non-tool row by message_seq (#N); each action is remove (replace the output with a tiny marker), summarize (replace it with a condensed replacement note), or truncate (keep the first max_chars). The conversation is never forked and never rewritten — the trim is re-applied to the model's prompt each turn and a user can toggle it off ("Show full"). Use it continuously: after reading or searching a lot, immediately compact the outputs that turned out useless so only what matters stays in context.

connect — manage external connection setup safelyCopy Anchor Link

{ "check": { "kind": "mcp", "id": "github" }, "list": { "kind": "mcp" } }

Result: a named handshake outcome followed by the current visible MCP assignments. The same five verbs — remove, add, check, authorize, list — cover MCP, channel, git, provider and source kinds. Every requested kind-specific feature is checked before the first mutation, and successful earlier operations remain explicit if a later runtime operation is refused. Secrets are never tool inputs or outputs: provider/git/channel setup returns a secure human handoff, and an OAuth URL is for the human to open.

execute with background: true — a shell that reports backCopy Anchor Link

{ "command": "pnpm build 2>&1", "background": true }

Result: { "shellId": "nrs-sh-…", "statusUri": "data://…/meta.json", "outputUri": "data://…/output.jsonl", "status": "running" } at once. The conversation continues by itself when the shell ends — the exit code and a bounded head + tail of the output arrive as the platform's own background_report result card, streamed live into the spawner's open browser when there is one — so the agent ends its turn instead of polling. The full log is readable any time with fs_read(outputUri). Listing, reading more and stopping are conversation routes (GET /shells, GET /shells/:id/output?since=, POST /shells/:id/kill), reached through the execute-skill scripts or the card's Kill control; they answer only for shells the caller started — a shell handle cannot be borrowed across callers — and stopping answers only for the agent that started it (403 shell_stop_forbidden from another agent's session).

Messaging another agent's conversationCopy Anchor Link

POST /api/packages/@neuralis/agent-core/conversations/<id>/inbox?agentId=<target>
{ "message": "The survey is in data://…/EVIDENCE.md — please review section 3.",
  "delivery": "settle" }

Result: 202 { "queued": true, "id": "msg_…" }. The message lands in that conversation as a report card naming the sender (the caller's own session — a body from is ignored) and the conversation continues by itself as the sender — a turn under the caller's own identity, never the owner's. The caller needs write access to the conversation and read access to the agent; sending to your own conversation is 400; the brakes answer 429 (inbox_hops_exceeded, inbox_full, inbox_rate_limited). GET …/inbox lists the undelivered messages, each with the delivery it was queued with; POST …/delegates/<runId>/inbox addresses a background subagent run's own inbox. The manage-conversations skill's queue.sh / inbox.sh wrap these.

delivery decides WHEN the receiver sees it. settle (the default) delivers it at the start of the receiver's next turn. immediate asks the turn that is already running to take it at its next step, so a correction reaches an agent while it still changes what that agent does. It is a request, not a guarantee: the platform keeps the message queued for the end of the turn — never drops it — when the running turn belongs to a different user, when its text can leave the platform (mirrored to a chat channel, bridged to one, or produced by a workflow run whose result may be announced to one), when the turn runs under a weaker guard than its conversation is configured with, when it is on its forced wrap-up step, or when it has already taken its ceiling of immediate messages for that turn. A background run's inbox has no mid-turn step at all, so immediate there answers 400 inbox_delivery_unsupported, and an unknown value answers 400 inbox_delivery_invalid.

Reading a transcript incrementallyCopy Anchor Link

GET /api/packages/@neuralis/agent-core/conversations/<id>/messages?agentId=<id>&sinceSeq=42

sinceSeq is INCLUSIVE — the response holds the rows from that sequence number onward, so a client that already has row 42 gets it back and replaces it. That is deliberate: when several tools run in parallel their results merge into one existing row, which keeps its sequence number, and an exclusive bound would never return the row that changed. The bound is decimal digits only — anything else (a negative, a fraction, 0x2, 1e3) answers 400 invalid_since_seq rather than being coerced or quietly returning the whole transcript. The same parameter works on …/delegates/<runId>/messages, behind the same read gate.

The workspace uses it with the live conversation notification channel, which is how a turn no browser is driving — a scheduled workflow run, a background subagent reporting back, a message from another agent — appears in an open tab without a reload.

Stopping the turn that is live in a conversationCopy Anchor Link

POST /api/packages/@neuralis/agent-core/conversations/<id>/stop?agentId=<agent>

Result: 200 { "ok": true, "stopped": true }. This reaches a turn nobody is holding a browser connection for — a background report, an inbox message being answered, a workflow run — which is the class the chat composer's own Stop cannot reach. The caller needs write access to the conversation, and then either owns the turn (a report runs as its spawner, a workflow as its creator) or holds admin strength; otherwise 403 stream_stop_forbidden. It is idempotent: nothing running answers "stopped": false. The turn ends cleanly — the partial answer is persisted and nothing offers to resume it — and a workflow turn also closes its run so a restart will not restart it. The manage-conversations skill's stop.sh wraps it.

"Cleanly" now includes the work already in flight. A running container shell command or subagent is stopped along with the turn (a host-plane command is only left behind — the turn stops waiting, the command finishes under its own timeout), an external MCP call is cancelled on the wire, and a tool that cannot be stopped is left to finish with its result dropped — so the conversation is released in seconds rather than waiting out whatever the tool was doing. Two things are deliberately exempt because they are built to outlive the turn: a background shell and a background subagent. Each has its own stop.

2. The HTTP route surfaceCopy Anchor Link

Every other client reaches agent-core through REST routes under /api/packages/@neuralis/agent-core/<pattern>. The kernel route dispatcher derives userId, projectId, and the optional agentId from the verified session — never from client-supplied values — and enforces each route's declared feature against the caller's grantedFeatures before the handler runs (deny-by-default; a caller lacking the feature gets 403, no data, no existence oracle).

The features themselves and their default role grants are documented on the package overview. A skill script calling these routes authenticates with the implicit per-stream session ticket — see the security page; it never forges identity in a header. External MCP clients use the OAuth 2.1 MCP endpoint, not these package routes.

3. The typed getPackageApi() consumer surfaceCopy Anchor Link

Another package never calls agent-core's HTTP routes and never calls it over MCP. It calls the typed, session-aware adapter:

import { getPackageApi } from '@neuralis/package-system';
import type { AgentCoreApi } from '@neuralis/agent-core';

const api = getPackageApi<AgentCoreApi>('@neuralis/agent-core', session);

This is the in-process path the lifecycle mandates: direct internal APIs for package-to-package calls, MCP reserved for the model and external clients. The returned AgentCoreApi exposes, among others:

The host verifies skill session tickets through the required session-ticket-verifier service registered at init. It returns the real live-stream session; the verifier is separate from the public AgentCoreApi.

agent-core consumes brain-core's filesystem API the exact same way — typed, through getPackageApi(), importing nothing across the boundary.

See alsoCopy Anchor Link

• Native tools — the deep dive on execute, delegate, and the web tools.
• package-system routes — how route patterns, params, and the feature gate work.
• package-system lifecycle — the getPackageApi() doctrine and the MCP-internal-forbidden rule.
• Security — the shell sandbox, URI-policy gating, the session ticket, and the MCP boundary.