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 23 MCP tool(s) for AI agent integration:
| Tool Name | Description |
|---|---|
| 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. |
| agent_delete_session | Deletes a session on an agent, removing the session record (history, pending messages, metadata). Use this to hold a private conversation and delete it afterwards. Job records are not touched — callers hold their own Job IDs and may delete those separately via the jobs API. Any in-flight chat on the session is failed. Operators may disable this operation via venue config (adapters.agent.sessionDelete: false). |
| agent_info | Get a lightweight summary of an agent: status, canonical config, pending-task count, timeline length, unavailable configured tools, and any suspension error. For durable detail inspect g/{agentId}: config is at g/{agentId}/config, audit runs at g/{agentId}/timeline, and conversations at g/{agentId}/sessions/<sessionId>/frames. Framework-managed records are read-only; use agent:update for config changes and agent:context for the exact next provider input. |
| agent_list | Lists all agents owned by the authenticated user, with a status summary for each. Terminated agents are hidden by default. |
| agent_reload_context | Explicitly invalidates one idle session's materialised provider prefix so its next inference rebuilds the system prompt, fixed tools, skill catalog and pinned context from current agent configuration. Conversation history and loaded context are preserved exactly. Ordinary agent updates do not do this implicitly. |
| agent_update | Update an agent's configuration and/or runtime state while preserving its history. Config accepts an inline map, a reference, or ordered layers; it is recursively merged over existing config with later values winning (vectors replace). State remains shallow-merged. Existing sessions keep their materialised prompt/tool prefix; use agent:reloadContext explicitly for an idle session that must adopt those changes. Agent configuration has one home: pass model, tools, caps, outputs, and systemPrompt under config; state.config is rejected. Framework-managed fields (status, tasks, inbox, timeline) are never affected. A running agent may be updated: config applies to future transitions (a transition already started keeps the snapshot it fired with; use agent:suspend to halt it now), and state is merged by the run loop as the transition's change against its fire-time snapshot, so keys the transition does not touch survive. The result's running flag says whether a transition was in flight; narrowing caps while one runs adds a warning. |
| agent_rename_session | Sets or clears the free-form human-facing title on a session. Omitting title (or passing an empty string) clears it back to unset. Titled sessions are easier to pick out in a session list than the raw id/timestamp. |
| agent_step | Step an agent's harness through one iteration without calling the model. Describe the call as for agent:context and supply the reply the model would give — text, tool calls, or both. The tool calls are dispatched exactly as a live cycle dispatches them (same routes, same capability checks, same authority — so the tools' own side effects are real), their results are rendered, and the prompt the next inference would receive is returned with what the iteration would have appended to the conversation. The agent itself is untouched: nothing persists to its session, timeline or tasks; complete_task/fail_task (llmagent) and complete/fail (goaltree) are validated as live but reported as the terminal outcome instead of resolving anything. subgoal (goaltree) is not run — it would start a child frame and call the model. |
| agent_create | Creates a new agent at g/<agentId> in the caller's namespace. The name must be unused; an existing agent is an error. To replace an agent, explicitly call agent:delete with remove=true and then create the new agent. Use agent:update for history-preserving config or state changes. Omit config for the recommended skilled default: bounded inspect plus read/list tools and skills loaded on demand, using the venue's default transition and LLM operation. Pass config={} only when you intentionally want an explicit minimal configuration. Config may be one inline map, one reference, or an ordered array of either. Ordered layers merge left-to-right: nested maps merge recursively and every later scalar/array value overrides the earlier value. Example: config=['v/agents/templates/worker', {llmOperation:'v/models/anthropic/claude-sonnet-5'}]. References may point to flat config maps or canonical Covia assets carrying an agent.config facet. 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. Prefer a model operation such as 'v/models/anthropic/claude-sonnet-5' for llmOperation. Legacy provider paths such as 'v/ops/langchain/anthropic' remain supported with an optional model override. Provider and model operations resolve API keys from the user's secret store via their default secretKey, or you can override with apiKey='s/<SECRET_NAME>'. After creation, send work via agent_request and inspect via agent_info. |
| 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. Creates no session. Defaults to blocking until the current cycle yields or finishes; set wait=false to return immediately, or wait=<ms> for a bounded wait. |
| agent_context | Assemble the exact context an agent would send to its model for one hypothetical call, without calling the model: the same Spec through the same assembler as a live transition. Describe the call — an inbox message (or several), pending job results, a task, a session — and receive the level-3 input (model, messages, tools, cacheMarks) plus budget and band diagnostics, palette provenance, load-resolution details and logical prefix hashes. With nothing to act on, the context shows the empty-state signal a wake-up would see. |
| agent_complete_task | Deliver the final result for the in-scope task and end it. This is terminal: the caller receives the result and nothing else. During an LLM transition, a long prose answer may be supplied as the message text with no result argument in the same turn; otherwise pass the answer in result. Only invoke this once the actual answer is ready. The agent and task are determined from the current request context — no id is passed. Without a task in scope the call fails. Side effects: completes the pending task Job and removes the task from the agent's task queue. |
| 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_fail_task | Reject or fail the in-scope task when the request cannot be fulfilled, for example because it is outside the agent's capabilities or its input is invalid. The agent and task are determined from the current request context — no id is passed. Without a task in scope the call fails. Side effects: fails the pending task Job with the supplied error 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_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 accepts one layer or an ordered layer array; it is resolved first, then recursively merged over the source config with later values winning. |
| agent_session_read | Reads a bounded, model-safe transcript projection. An agent may omit agentId to inspect itself; an owner or authorised caller supplies agentId. Omit sessionId for the newest visible session. Compacted history is retained and can be opened to a bounded depth. The caller's current session, missing sessions and sessions hidden by venue policy all return exactly {found:false}. Tool scratch, diagnostics and unanswered turns are omitted. |
| agent_compact_session | Replaces an idle session's visible conversation with one assistant-memory summary while retaining the exact replaced history nested under the compaction record for audit. Future turns append normally. The result is bounded metadata; it does not duplicate the archived transcript. |
| agent_sessions | Lists bounded metadata for past conversations, newest first. An agent may omit agentId to inspect itself; an owner or authorised caller supplies agentId. The caller's current session, unfinished conversations and sessions hidden by venue policy are omitted. This is a safe projection, not generic access to agent state. |
| agent_delete | Terminates one agent or an exact list of agents in a single Job. Supply exactly one of agentId or agentIds; prefixes and wildcard deletion are not supported. By default records are preserved with TERMINATED status for audit. Set remove=true to remove records entirely, freeing their names and making unreachable storage eligible for Etch garbage collection. Every requested ID is validated before deletion begins. |
| 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. Several chats may be in flight on one session at once — they are not rejected; each awaits the agent's next response, and a response answers every message the agent had already seen, so quick successive messages may share one reply. |
| 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. An optional reason becomes the cancelled task job's error, so whoever is waiting on it sees why. |
| 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. |