Agents

Define, version, release, run, and export or import governed SOIT agents as YAML or JSON files.

Agents are the primary business object in SOIT. An agent combines instructions, model choices, knowledge, tools, workflows, memory, and governance policy into a versioned runtime unit.

When to use agents

Use an agent when a user-facing or system-facing AI capability needs governed access to models, knowledge, tools, and workflows. Agents are appropriate for assistants, customer support automation, internal copilots, and production workflows that require traceability.

Anatomy of an agent

An agent definition (validated against the agent.v1 spec schema) assembles typed capability bindings:

Binding	What it grants
Model	Which LLM reference the agent executes with (e.g. `model:openai:gpt-4.1`)
Knowledge	Which knowledge bases ground the agent's answers, with citations
Tools	Which governed tools the agent may call — built-in, plugin-exported, or MCP-backed
Workflows	Which workflows the agent can invoke as child runs
Memory	Whether and how the agent persists scoped context across runs

Bindings are source-agnostic: a plugin tool, an MCP tool, and a built-in tool look identical in the agent spec.

Version and release lifecycle

Editing an agent creates a new immutable version; the head pointer advances.
Publishing promotes a chosen version to live and writes a release ledger record.
Formal execution always uses the published version — execute-payload overrides cannot swap bindings, and drafts are only reachable through explicit preview.
Rollback moves the live pointer back with full provenance (GET /api/v1/agents/{agent_id}/releases).
A regression evaluation can gate publishing, so a version that breaks the golden prompt set never goes live.

Agent files

New in v1.5.0. An agent moves in and out as a YAML or JSON file, for version control or for another workspace:

GET  /api/v1/agents/{agent_id}/export
POST /api/v1/agents/import

Export answers the agent's own fields (name, description, visibility, category, icon, tags) and its published version's specification, or its current version's when none is published, in the shape a new version is created from. Ids, ownership, and counters are left out, since they mean nothing in another workspace.
Import creates a new agent from such a document, and its version as a draft, through the same validation and binding resolution as creating them by hand, so a re-created version has the exported version's checksum. The model, tool, and knowledge refs the file names must exist in the importing workspace, or the import is refused as a version creation would be.
Export needs read access to the agent; import needs workspace write access.

The document names its format in soit:

soit: agent/v1
agent:
  name: Support agent
  description: Answers refund and shipping questions
  visibility: private
version:
  system_prompt: You answer customer questions with citations.
  temperature: 0.2
  # … the rest of the version specification, as exported

The API speaks the document as JSON. From a terminal, soit agent export writes it as YAML and soit agent import reads YAML or JSON.

How agents connect

Agents bind to Models for LLM execution.
Agents retrieve from Knowledge with citation evidence.
Agents call tools exported by Plugins and MCP and Skills.
Agents can invoke Workflows as child runs.
Every agent execution records Tasks and Runs evidence: steps, costs, citations, audits.

API and UI surfaces

API prefix: /api/v1/agents (definitions, versions, releases, execution views, export and import)
CLI: soit agent export and soit agent import
Related API prefixes: /api/v1/threads, /api/v1/responses, /api/v1/runs
Web routes: /agents (workbench), /chat (conversation), /observe (execution evidence)