Invoke agent

veryfront__invoke_agent

Returns the child agent reply.

Access

This tool runs inside a project agent runtime. Attach it to an agent; it cannot be called directly through POST /mcp.

Call type: Can change resources.

Arguments

FieldTypeRequiredDescription and constraints
promptstringYesRequired handoff prompt for the delegated run.
task_idstringNoOptional stable project task id. Reuse the same project, principal, agent and task id to replay one durable child, including after completion. The admitting parent retains ownership; another parent receives a conflict. Use a new task id for new work. Minimum length: 1. Maximum length: 200.
context_modestringNoOptional context policy for the first task admission. Omit or use continue to include the current conversation branch. Use fresh to start the child model from only the handoff packet. Task replay returns the original run. Values: "continue", "fresh".
idempotency_scopestringNoOptional exact-once scope for an immutable durable-task invocation. Requires task_id. Task ids already select one durable child across tool-call retries, including after completion. Use a new task id for a new run. Values: "durable_task".
contextobjectNoStructured data payload for the child task. Use this for critical facts, records, ids, decisions, and values the child must act on instead of copying those facts as prose. Defaults to {} when the delegation has no record or evidence payload. Default: {}.
evidence_refsobject[]NoOptional generic source-of-truth references for facts the child must preserve. Prefer run_id/message_id/tool_call_id plus result_path over copying critical facts as prose.
descriptionstringNoOptional short summary of the delegated task for UI and audit display.
agent_idstringNoOptional agent id. Must be the exact id from agent discovery (e.g. list_agents), without any prefix or namespace. Defaults to the current agent.
project_idstringNoOptional exact project UUID for cross-project delegation. Defaults to the current project.
runtime_target_kindstringNoOptional exact runtime target override. Leave unset unless the user explicitly asked to switch targets. Values: "main_branch", "environment", "preview_branch".
target_environment_idstringNoRequired only for a real environment target override and must be the exact environment UUID.
target_branch_idstringNoRequired only for a real preview branch override and must be the exact branch UUID.
source_target_kindstringNoOptional source target override for agent config discovery. Leave unset unless the user explicitly asked to change it. Values: "project", "main_branch", "environment", "preview_branch".
allow_delegationbooleanNoOptional. When true, the child run may invoke invoke_agent again. Defaults to false for child runs.
toolsstring[]NoOptional exact allowlist of tool names for the child run. Omit to inherit all available tools.
modelstringNoOptional model override for the child run. Must be allowed by the target agent if restricted.
thinkingboolean or integerNoOptional thinking override. When omitted, project-defined child runs use the selected agent config and projectless child runs use the platform default. Use false to disable or a positive integer budget when the runtime supports it.
max_stepsintegerNoOptional max-steps override for the child run. Minimum: 1.

Result

No output schema is published for this tool. The input contract does not define its return fields. Inspect the MCP response content and isError; do not assume a fixed object shape.

Full schemas

json
{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "Required handoff prompt for the delegated run."
    },
    "task_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]*$",
      "description": "Optional stable project task id. Reuse the same project, principal, agent and task id to replay one durable child, including after completion. The admitting parent retains ownership; another parent receives a conflict. Use a new task id for new work."
    },
    "context_mode": {
      "type": "string",
      "enum": [
        "continue",
        "fresh"
      ],
      "description": "Optional context policy for the first task admission. Omit or use continue to include the current conversation branch. Use fresh to start the child model from only the handoff packet. Task replay returns the original run."
    },
    "idempotency_scope": {
      "type": "string",
      "enum": [
        "durable_task"
      ],
      "description": "Optional exact-once scope for an immutable durable-task invocation. Requires task_id. Task ids already select one durable child across tool-call retries, including after completion. Use a new task id for a new run."
    },
    "context": {
      "type": "object",
      "default": {},
      "description": "Structured data payload for the child task. Use this for critical facts, records, ids, decisions, and values the child must act on instead of copying those facts as prose. Defaults to {} when the delegation has no record or evidence payload.",
      "additionalProperties": true
    },
    "evidence_refs": {
      "type": "array",
      "description": "Optional generic source-of-truth references for facts the child must preserve. Prefer run_id/message_id/tool_call_id plus result_path over copying critical facts as prose.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "run_id": {
            "type": "string"
          },
          "message_id": {
            "type": "string"
          },
          "tool_call_id": {
            "type": "string"
          },
          "result_path": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          }
        }
      }
    },
    "description": {
      "type": "string",
      "description": "Optional short summary of the delegated task for UI and audit display."
    },
    "agent_id": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_-]+$",
      "description": "Optional agent id. Must be the exact id from agent discovery (e.g. list_agents), without any prefix or namespace. Defaults to the current agent."
    },
    "project_id": {
      "type": "string",
      "description": "Optional exact project UUID for cross-project delegation. Defaults to the current project."
    },
    "runtime_target_kind": {
      "type": "string",
      "enum": [
        "main_branch",
        "environment",
        "preview_branch"
      ],
      "description": "Optional exact runtime target override. Leave unset unless the user explicitly asked to switch targets."
    },
    "target_environment_id": {
      "type": "string",
      "description": "Required only for a real environment target override and must be the exact environment UUID."
    },
    "target_branch_id": {
      "type": "string",
      "description": "Required only for a real preview branch override and must be the exact branch UUID."
    },
    "source_target_kind": {
      "type": "string",
      "enum": [
        "project",
        "main_branch",
        "environment",
        "preview_branch"
      ],
      "description": "Optional source target override for agent config discovery. Leave unset unless the user explicitly asked to change it."
    },
    "allow_delegation": {
      "type": "boolean",
      "description": "Optional. When true, the child run may invoke invoke_agent again. Defaults to false for child runs."
    },
    "tools": {
      "type": "array",
      "description": "Optional exact allowlist of tool names for the child run. Omit to inherit all available tools.",
      "items": {
        "type": "string"
      }
    },
    "model": {
      "type": "string",
      "description": "Optional model override for the child run. Must be allowed by the target agent if restricted."
    },
    "thinking": {
      "description": "Optional thinking override. When omitted, project-defined child runs use the selected agent config and projectless child runs use the platform default. Use false to disable or a positive integer budget when the runtime supports it.",
      "anyOf": [
        {
          "type": "boolean",
          "enum": [
            false
          ]
        },
        {
          "type": "integer",
          "minimum": 1
        }
      ]
    },
    "max_steps": {
      "type": "integer",
      "minimum": 1,
      "description": "Optional max-steps override for the child run."
    }
  },
  "required": [
    "prompt"
  ]
}

Agent runtime

Use the Agents API to configure the agent's tools. Start the agent through the Execution API. The runtime supplies the execution context for this tool.