diff --git a/Agents.md b/Agents.md index 6333ffc..2ddc271 100644 --- a/Agents.md +++ b/Agents.md @@ -155,6 +155,12 @@ The `variables` setting in an agent's config has the following fields: | `description` | * | The description of the field | | `default` | | A default value for the field. If left undefined, the user will be prompted for a value at runtime | +Variable values can be supplied three ways (highest precedence first): + +1. **At spawn time:** A parent agent passes them via `agent__spawn`'s / `agent__task_create`'s `variables` parameter (see [Passing Agent Variables at Spawn](#passing-agent-variables-at-spawn)). Spawned child agents also inherit the parent's CLI-set variables by name as a fallback. +2. **On the CLI:** `coyote -a my-agent --agent-variable "..."`. +3. **Declared `default`:** Used when nothing else supplies a value. A required variable (no default) with no supplied value triggers an interactive prompt at startup, except for spawned child agents, which never prompt (see below). + These variables can be referenced in both the agent's instructions, and in the tool definitions via `LLM_AGENT_VAR_`. **Example:** @@ -627,10 +633,10 @@ When `can_spawn_agents` is enabled, the agent receives tools for spawning and ma | Tool | Description | |-------------------------|------------------------------------------------------------------------------------------------------------------------| -| `agent__spawn` | Spawn a child agent in the background. Returns an agent ID immediately. | +| `agent__spawn` | Spawn a child agent in the background, optionally passing its declared `variables`. Returns an agent ID immediately. | | `agent__check` | Non-blocking check: is the agent done? Returns `PENDING` or the result. | | `agent__collect` | Blocking wait: wait for an agent to finish, return its output. | -| `agent__list_available` | List all agent types installed and available to spawn (name + description). Discovery counterpart to `agent__spawn`. | +| `agent__list_available` | List all agent types installed and available to spawn (name + description + declared variables). Discovery counterpart to `agent__spawn`. | | `agent__list_running` | List all subagents you have spawned, with their status. | | `agent__cancel` | Cancel a running agent by ID. | @@ -656,6 +662,52 @@ Any agent defined in your `/agents/` directory can be spawned - Have their output suppressed from the terminal (no spinner, no tool call logging) - Return their accumulated output to the parent when collected +### Passing Agent Variables at Spawn + +`agent__spawn` accepts an optional `variables` parameter (an object of string values). This is the spawn-time +equivalent of the CLI's `--agent-variable`: + +``` +agent__spawn --agent pr-reviewer --variables {"pr": "1234"} --prompt "Review this PR." +``` + +**Discovering an agent's variables.** `agent__list_available` advertises each agent's declared +variables, so a parent can learn the spawn contract up front: + +```json +{ + "name": "pr-reviewer", + "description": "Reviews pull requests", + "variables": [ + { "name": "pr", "description": "The PR URL or number", "required": true } + ] +} +``` + +`required` is `true` when the variable declares no `default`; the `variables` key is omitted for +agents that declare none. + +**Precedence.** For each declared variable, the value is resolved in this order: + +1. The spawn call's `variables` entry +2. A same-named variable inherited from the parent (e.g. set on the parent via `--agent-variable`) +3. The variable's declared `default` + +**Validation and error behavior.** Unknown variable names, non-string values, or passing +`variables` to an agent that declares none all return a self-correcting error listing the target +agent's declared variables. Spawned children never trigger the interactive variable prompt: if a +required variable ends up with no value, the spawn fails with an error naming each missing +variable so the parent can re-spawn with the right `variables`. + +**Notes:** +- Values reach the child's instructions (`{{name}}` interpolation), its tools + (`LLM_AGENT_VAR_`), and, for [graph agents](Graph-Agents), the initial graph state, so + `{{name}}` resolves inside `llm` node prompts. +- If the target agent is configured with a persistent `agent_session` and an existing session is + resumed, the session's stored variables win and spawn-provided `variables` are ignored. +- `agent__task_create` accepts the same `variables` parameter for auto-dispatched tasks (see + [Active Task Dispatch](#active-task-dispatch)). + ## Task Queue with Dependencies For complex workflows where tasks have ordering requirements, the spawning system includes a dependency-aware @@ -663,7 +715,7 @@ task queue: | Tool | Description | |------------------------|-----------------------------------------------------------------------------| -| `agent__task_create` | Create a task with optional dependencies and auto-dispatch agent. | +| `agent__task_create` | Create a task with optional dependencies, auto-dispatch agent, and agent `variables`. | | `agent__task_list` | List all tasks with their status, dependencies, and assignments. | | `agent__task_complete` | Mark a task done. Returns newly unblocked tasks and auto-dispatches agents. | | `agent__task_fail` | Mark a task as failed. Dependents remain blocked. | @@ -687,11 +739,15 @@ agent__task_create \ --subject "Implement the auth module" \ --blocked_by ["task_1"] \ --agent coder \ + --variables {"project_dir": "/path/to/repo"} \ --prompt "Implement auth module based on patterns found in task_1" ``` When `task_1` completes and the dependent task becomes unblocked, an agent is automatically spawned with the -specified prompt. No manual intervention needed. This enables fully automated multi-step pipelines. +specified prompt, and with the task's stored `variables` passed through to the spawn, exactly as if they +had been given to `agent__spawn` directly (same precedence and validation). `agent__task_list` echoes each +task's `variables` alongside its prompt. No manual intervention needed. This enables fully automated +multi-step pipelines. ## Output Summarization diff --git a/Graph-Agents.md b/Graph-Agents.md index d148748..2e70eda 100644 --- a/Graph-Agents.md +++ b/Graph-Agents.md @@ -132,10 +132,12 @@ nodes: Each declared variable becomes available to script nodes as the env var `LLM_AGENT_VAR_`, exactly like bash tools called by normal agents. Values may be overridden at runtime via - `coyote -a --agent-variable "..."`. For LLM nodes to - see a variable inside prompts, seed its value into state (typically via - a setup script that reads the env var and writes it into state) so - `{{name}}` resolves. + `coyote -a --agent-variable "..."` (or when the + graph agent is spawned as a subagent), via `agent__spawn`'s `variables` + parameter (see [Passing Agent Variables at Spawn](Agents#passing-agent-variables-at-spawn)). + Declared variables are seeded into the initial graph state automatically + (resolved value first, then declared default), so `{{name}}` resolves + inside `llm` node prompts with no setup script required. - **`can_spawn_agents` is declared, or derived when omitted.** When the key is absent, a graph agent can spawn dynamic child agents iff its graph contains at least one `agent` node; an explicit value overrides that