Skip to main content

Agents

Covia agents are persistent, stateful AI actors that live on a venue. They receive tasks, call tools, coordinate with other agents, and produce auditable results — all within the venue's governance and capability framework.

Key Concepts​

An agent is more than a chat session. It is a durable record with:

  • Configuration — system prompt, tools, capabilities, LLM backend
  • Sessions — persistent conversation threads; each holds its own messages, conversation, and scratch data that persist across runs
  • Tasks — tracked requests (Jobs) from humans, other agents, or systems
  • Timeline — an append-only audit trail of every completed run

See Sessions for how work flows into an agent.

Agents are created by callers and scoped to their owner. Two different users can each have an agent named "Alice" without collision.

Architecture​

The agent system separates concerns into three pluggable levels:

Level 1: Framework          Level 2: Domain Logic       Level 3: LLM
agent:trigger               goaltree:chat               langchain:openai
agent:request        -->    llmagent:chat        -->    langchain:anthropic
agent:message               (custom)                    langchain:ollama

Level 1 (Framework) manages the agent lifecycle — picking up inbound tasks and session messages, invoking the transition function, recording results in the timeline, and persisting state. It never inspects the conversation or user data.

Level 2 (Domain Logic) manages the session conversation, tool call loops, and context assembly. Two built-in options:

AdapterOperationBest for
LLM Agentllmagent:chatSimple conversational agents, flat history
Goal Treegoaltree:chatComplex tasks with hierarchical subgoals, typed outputs

Level 3 (LLM Call) is a stateless request/response to the language model. See LLM Backends for available providers.

Agent States​

An agent transitions through four states:

              create
                |
                v
  resume --> SLEEPING <-- (run completes successfully)
                |
            trigger / request
                |
                v
             RUNNING
              /    \
             v      v
         SLEEPING  SUSPENDED  (error)
                      |
                   resume
StateDescription
SLEEPINGIdle, ready to run. Default after creation or a successful run.
RUNNINGA transition is in flight. New tasks and messages are queued.
SUSPENDEDLast run failed. Dormant — does not auto-retry. State and tasks are preserved for debugging.
TERMINATEDLogically deleted. Preserves audit record; can be revived with overwrite: true.

Quick Example​

Create an agent, send it a task, and wait for the result:

// 1. Create
POST /api/v1/invoke
{
  "operation": "v/ops/agent/create",
  "input": {
    "agentId": "Alice",
    "config": {
      "systemPrompt": "You are Alice, a helpful research assistant.",
      "model": "gpt-5.4-mini",
      "tools": ["v/ops/covia/read", "v/ops/covia/list"]
    }
  }
}

// 2. Send a task (waits up to timeout ms for the result)
POST /api/v1/invoke
{
  "operation": "v/ops/agent/request",
  "input": {
    "agentId": "Alice",
    "input": { "task": "Summarise the vendor records" },
    "timeout": 30000
  }
}

Or via MCP tools in Claude Desktop:

agent_create  agentId: "Alice"  config: { systemPrompt: "...", tools: [...] }
agent_request agentId: "Alice"  input: { task: "Summarise the vendor records" }  timeout: 30000

What's Next​