create_agent
Create or update a pooled agent for a specific task, assigned a stable key for retrieval and reuse.
Instructions
Assemble an agent for a task and store it in the pool under agent_key, returning the
stored entry — the create/update entry point an orchestrating agent uses to stand up a new
pooled agent (or re-assemble an existing one).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional display name; auto-slugged from the task when omitted. | |
| tags | No | Optional routing tags to narrow recall and to label the stored entry. | |
| task | Yes | What the generated agent should do — the job it is being built to perform. | |
| team | No | Name of the team that owns the generated agent. | default |
| model | No | Which model the agent runs on; `inherit` defers to the caller's model. | inherit |
| pinned | No | Capability ids to force into the selection regardless of relevance score. | |
| agent_key | Yes | Stable external identifier for the pooled agent a caller manages — assign your own scheme (a ticket id, a slug, a UUID, anything meaningful to your use case). The pool's logical lookup key; distinct from the human-readable display name, and distinct from the harness's per-dispatch `AgentId`. | |
| reset_session | No | When True, mint a fresh session UUID even if the id already exists. | |
| system_prompt | No | A full system-prompt override; when omitted, one is templated from the task and the selected tools/skills. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | ||
| name | Yes | The agent's unique name — lowercase letters, digits, and dashes. | |
| spec | Yes | The canonical agent definition the pipeline assembles and the Claude Agent SDK emitter renders into a runnable program. `tools` and `mcp_servers` are kept separate here; the merged SDK tool-grant is derived at emission by `engine.render.tool_grant`. | |
| agent_key | Yes | Stable external identifier for the pooled agent a caller manages — assign your own scheme (a ticket id, a slug, a UUID, anything meaningful to your use case). The pool's logical lookup key; distinct from the human-readable display name, and distinct from the harness's per-dispatch `AgentId`. | |
| created_at | Yes | ||
| session_id | Yes | The Claude Agent SDK session UUID a pool entry pins and resumes — a lowercase-hex UUID, generated internally, never the human-readable pool name. | |
| updated_at | Yes |