Manages agent lifecycle: create agents, submit requests, deliver messages, and run their transition loop. Agents are per-user, identified by human-readable names, with persistent state in the lattice.
| Name: | agent |
| Class: | covia.adapter.AgentAdapter |
This adapter provides 16 MCP tool(s) for AI agent integration:
| Tool Name | Description |
|---|---|
| agent_suspend | Manually suspends an agent, preventing any future runs until explicitly resumed. If the agent is currently running, the current run will complete but no further runs will start. |
| agent_fork | Forks an existing agent — creates a new agent with the same config and state as the source. The forked agent starts SLEEPING with fresh tasks, pending, and inbox collections; timeline is copied only if includeTimeline is true. Use for branching exploration (try different prompts from a common starting point), scaling (spawn parallel workers from a trained agent), or snapshots before risky operations. Optional config overrides are merged on top of the source config. |
| agent_context | Render the exact L3 input (messages + tools + model) an agent would receive on a fresh transition, as pretty-printed JSON. Includes system prompt, context entries, harness tools (with typed schemas when outputs is set), and base tools. Pass an optional task to see the complete first-iteration message vector including the synthesised goal. |
| agent_cancel_task | Removes a pending task from an agent's task queue. The task will no longer be presented to the agent's transition function. Use this to clean up stuck or unwanted tasks. |
| agent_delete | Terminates an agent. The agent will no longer accept messages, tasks, or triggers. By default the agent record is preserved (TERMINATED status) for audit purposes. Set remove=true to delete the record entirely, freeing the name for reuse. |
| agent_chat | Send a message to an agent and synchronously await its next response on the session. Mints a new session when sessionId is omitted (returned in the response); continues an existing session when sessionId is supplied. A2A message/send analogue. Use this for conversational interactions where you need a reply. Use agent_request for tracked task delegation, or agent_message for fire-and-forget notifications. Only one chat may be in flight per session — concurrent calls on the same session are rejected. |
| agent_info | Get a lightweight summary of an agent: status, config, capabilities, task count, timeline length, and any error. For more detail use covia_read: g/{agentId}/state/config (LLM settings, caps, context), g/{agentId}/state/history (conversation), g/{agentId}/timeline (run records), g/{agentId}/inbox (pending messages). |
| agent_list | Lists all agents owned by the authenticated user, with a status summary for each. Terminated agents are hidden by default. |
| agent_fail_task | Explicitly marks the in-scope task as failed. Invoked by an agent transition (typically as an LLM tool call) to surface a non-recoverable error to the caller. The agentId and taskId are read from the request context — the framework populates them when dispatching a task transition. Without a task in scope the call fails. Side effects: fails the pending task Job with the supplied error message and removes the task from the agent's task queue. |
| agent_resume | Resumes a suspended agent, clearing any error and setting status to SLEEPING. If the agent has pending work (tasks or inbox messages), it will be woken immediately. |
| agent_complete_task | Explicitly marks the in-scope task as successfully complete. Invoked by an agent transition (typically as an LLM tool call) to deliver the final result to the caller. The agentId and taskId are read from the request context — the framework populates them when dispatching a task transition. Without a task in scope the call fails. Side effects: completes the pending task Job with the supplied result and removes the task from the agent's task queue. |
| agent_message | Send a fire-and-forget notification to an agent's inbox. NO response is returned — use agent_request instead if you need a reply. Messages are ephemeral notifications, not tracked tasks. Only use this for one-way alerts or events where you do not need the agent to respond. |
| agent_update | Update an agent's configuration and/or state. Both `config` and `state.config` are shallow-merged into the existing values — partial updates preserve siblings. Updating just `state.config.model` keeps tools, caps, outputs, and systemPrompt intact. Framework-managed fields (status, tasks, inbox, timeline) are never affected. Use this to tweak agent settings without recreating. |
| agent_trigger | Fallback kick that nudges the agent's run loop to execute a cycle. Not a result-getter — trigger carries no payload and makes no guarantee about what the agent produces. For results, await the relevant Job: submit work via agent:request (task Job) or agent:chat (chat Job) and wait on that. Use agent:trigger only when something outside the normal intake path needs a nudge — e.g. after a manual state edit, for diagnostics, or to resume a stuck agent. Defaults to blocking until the current cycle yields or finishes; set wait=false to return immediately, or wait=<ms> for a bounded wait. |
| agent_create | Creates an agent at g/<agentId> in the caller's namespace. Idempotent on empty slots — call again with the same agentId without overwrite=true and you get a no-op success. Slot resolution when overwrite=true: empty → create SLEEPING → update config in place (timeline preserved) SUSPENDED → update config in place (timeline preserved) TERMINATED → wipe and re-create fresh RUNNING → rejected (suspend or wait for it to finish first) Minimal example: agent_create(agentId='Helper', config={operation: 'v/ops/llmagent/chat', systemPrompt: 'You summarise documents.'}). The 'operation' field must be a resolvable lattice path (e.g. 'v/ops/llmagent/chat' for plain persona chat, 'v/ops/goaltree/chat' for goal-decomposing planners) — bare adapter shorthand like 'llmagent:chat' will not resolve. The default transition is v/ops/llmagent/chat with the venue's default LLM provider (OpenAI). To use a different provider, set llmOperation in config (e.g. 'v/ops/langchain/anthropic' for Claude, 'v/ops/langchain/ollama' for local models); each provider op resolves its API key from the user's secret store via its own default secretKey, or you can override with apiKey='s/<SECRET_NAME>'. After creation, send work via agent_request and inspect via agent_info. |
| agent_request | Send a request to an agent. PRIMARY tool for agent delegation. Best-effort synchronous: by default waits up to 5 seconds for the agent to finish. If the agent completes in time you get its structured response directly. If not, you get a snapshot {id, status: STARTED, agentId, sessionId} — poll with grid_job_result(id=<that id>, timeout=<ms>) to retrieve the result. Example: agent_request(agentId='Helper', input={task: 'summarise w/notes/daily'}, timeout=30000). For quick jobs set a short timeout; for slow jobs set timeout=0 (pure async) and poll via grid_job_result. For structured output, pass responseSchema. |