> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke agent

> Invoke an agent on a hidden child run for delegated or self-directed work.

export const McpToolCall = ({tool, initialArguments = {}, requiresConfirmation = false}) => {
  const validateCall = function validateReferenceToolCall(token, text, requiresConfirmation, confirmed) {
    if (!token.trim()) return {
      error: "Paste a bearer token first."
    };
    let value;
    try {
      value = JSON.parse(text.trim() || "{}");
    } catch {
      return {
        error: "Arguments must be valid JSON."
      };
    }
    if (!value || typeof value !== "object" || Array.isArray(value)) return {
      error: "Arguments must be a JSON object."
    };
    if (requiresConfirmation && !confirmed) return {
      error: "Confirm the tool call before running it."
    };
    return {
      arguments: value
    };
  };
  const endpoint = "https://api.veryfront.com/mcp";
  const tokenStorageKey = 'veryfront.docs.mcpBearerToken';
  const escapeHtml = value => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
  const highlightJson = value => {
    const escaped = escapeHtml(value);
    return escaped.replace(/("(?:\\u[a-fA-F0-9]{4}|\\[^u]|[^\\"])*"(\s*:)?|\btrue\b|\bfalse\b|\bnull\b|-?\d+(?:\.\d+)?(?:[eE][+\-]?\d+)?)/g, match => {
      let color = '#f3f4f6';
      if (match.endsWith(':')) {
        color = '#7dd3fc';
      } else if (match.startsWith('"')) {
        color = '#86efac';
      } else if ((/true|false/).test(match)) {
        color = '#c4b5fd';
      } else if ((/null/).test(match)) {
        color = '#fcd34d';
      } else {
        color = '#67e8f9';
      }
      return `<span style="color: ${color}">${match}</span>`;
    });
  };
  const expandJsonStrings = value => {
    if (typeof value === 'string') {
      const trimmed = value.trim();
      if (trimmed.startsWith('{') && trimmed.endsWith('}') || trimmed.startsWith('[') && trimmed.endsWith(']')) {
        try {
          return expandJsonStrings(JSON.parse(trimmed));
        } catch {}
      }
      return value;
    }
    if (Array.isArray(value)) {
      return value.map(expandJsonStrings);
    }
    if (value && typeof value === 'object') {
      return Object.fromEntries(Object.entries(value).map(([key, nestedValue]) => [key, expandJsonStrings(nestedValue)]));
    }
    return value;
  };
  const formatJson = value => {
    try {
      return JSON.stringify(expandJsonStrings(value), null, 2);
    } catch {
      return String(value);
    }
  };
  const formatResponseText = text => {
    const trimmed = text.trim();
    if (!trimmed) return 'No response body.';
    try {
      return formatJson(JSON.parse(trimmed));
    } catch {}
    const ssePayloads = trimmed.split(/\n\n+/).flatMap(chunk => chunk.split('\n').filter(line => line.startsWith('data:')).map(line => line.slice(5).trim()).filter(Boolean));
    for (let index = ssePayloads.length - 1; index >= 0; index -= 1) {
      try {
        return formatJson(JSON.parse(ssePayloads[index]));
      } catch {}
    }
    return trimmed;
  };
  const readStoredToken = () => {
    if (typeof window === 'undefined') return '';
    try {
      return window.sessionStorage.getItem(tokenStorageKey) || '';
    } catch {
      return '';
    }
  };
  const writeStoredToken = value => {
    if (typeof window === 'undefined') return;
    try {
      if (value) {
        window.sessionStorage.setItem(tokenStorageKey, value);
      } else {
        window.sessionStorage.removeItem(tokenStorageKey);
      }
    } catch {}
  };
  const [token, setToken] = useState(readStoredToken);
  const [argumentText, setArgumentText] = useState(formatJson(initialArguments));
  const [status, setStatus] = useState('Ready');
  const [response, setResponse] = useState('No response yet.');
  const [copied, setCopied] = useState(false);
  const [confirmed, setConfirmed] = useState(false);
  const callTool = async () => {
    const validation = validateCall(token, argumentText, requiresConfirmation, confirmed);
    if (('error' in validation)) {
      setStatus(validation.error);
      return;
    }
    const parsedArguments = validation.arguments;
    setConfirmed(false);
    const body = {
      jsonrpc: '2.0',
      id: Date.now(),
      method: 'tools/call',
      params: {
        name: tool,
        arguments: parsedArguments
      }
    };
    setStatus('Calling tool...');
    setResponse(formatJson(body));
    try {
      const result = await fetch(endpoint, {
        method: 'POST',
        headers: {
          accept: 'application/json, text/event-stream',
          'content-type': 'application/json',
          authorization: `Bearer ${token.trim()}`,
          'x-veryfront-origin': 'docs-mcp-tool-page'
        },
        body: JSON.stringify(body)
      });
      const text = await result.text();
      setStatus(result.ok ? 'Response received.' : `Request failed with HTTP ${result.status}.`);
      setResponse(formatResponseText(text));
    } catch (error) {
      setStatus('Request failed.');
      setResponse(error instanceof Error ? error.message : String(error));
    }
  };
  const copyResponse = async () => {
    try {
      await navigator.clipboard.writeText(response);
      setCopied(true);
      setTimeout(() => setCopied(false), 1500);
    } catch {
      setStatus('Copy failed.');
    }
  };
  return <details className="api-try-operation not-prose">
    <summary>Try this tool</summary>
    <p>Replace sample arguments with values for your project or connected account. Calls run only when you select Run tool.</p>
    <div className="api-request-playground not-prose my-6 rounded-xl border border-gray-200 bg-white p-4 dark:border-gray-800 dark:bg-gray-950">
      <div className="mb-4">
        <div className="text-sm font-semibold text-gray-900 dark:text-gray-100">MCP tool call</div>
        <div className="mt-1 text-sm text-gray-600 dark:text-gray-400">
          Call <code>{tool}</code> against the Veryfront MCP endpoint.
        </div>
      </div>

      <label className="mb-2 block text-sm font-medium text-gray-900 dark:text-gray-100" htmlFor={`${tool}-token`}>
        Bearer token or API key
      </label>
      <input id={`${tool}-token`} className="mb-4 w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-100" type="password" value={token} onChange={event => {
    const value = event.target.value;
    setToken(value);
    setConfirmed(false);
    writeStoredToken(value);
  }} placeholder="Paste API key or JWT" />

      <label className="mb-2 block text-sm font-medium text-gray-900 dark:text-gray-100" htmlFor={`${tool}-arguments`}>
        Arguments (JSON)
      </label>
      <textarea id={`${tool}-arguments`} className="mb-4 min-h-40 w-full rounded-md border border-gray-300 bg-white px-3 py-2 font-mono text-sm text-gray-900 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-100" value={argumentText} onChange={event => {
    setArgumentText(event.target.value);
    setConfirmed(false);
  }} spellCheck={false} />

      {requiresConfirmation && <label className="api-request-confirmation mb-4 flex items-start gap-2 text-sm">
        <input type="checkbox" checked={confirmed} onChange={event => setConfirmed(event.target.checked)} />
        <span>{tool === 'veryfront__set_project_inference_policy' ? 'Replace the project inference policy with these arguments. Omitted constraints will be removed.' : 'Run this tool with these arguments.'}</span>
      </label>}
      <button disabled={status === 'Calling tool...' || requiresConfirmation && !confirmed} className="disabled:opacity-50 disabled:cursor-not-allowed rounded-md bg-gray-900 px-3 py-2 text-sm font-medium text-white hover:bg-gray-700 dark:bg-gray-100 dark:text-gray-950 dark:hover:bg-gray-300" type="button" onClick={callTool}>
        Run tool
      </button>

      <div className="mt-4 text-sm font-medium text-gray-900 dark:text-gray-100">{status}</div>
      <div className="mt-3 overflow-hidden rounded-md border border-gray-300 dark:border-gray-700">
        <div className="flex items-center justify-between bg-gray-100 px-3 py-2 text-sm font-medium text-gray-900 dark:bg-gray-900 dark:text-gray-100">
          <span>Output JSON</span>
          <button className="rounded border border-gray-300 bg-white px-2 py-1 text-xs text-gray-900 hover:bg-gray-50 dark:border-gray-700 dark:bg-gray-950 dark:text-gray-100 dark:hover:bg-gray-800" type="button" onClick={copyResponse}>
            {copied ? 'Copied' : 'Copy'}
          </button>
        </div>
      <pre className="max-h-96 overflow-auto whitespace-pre-wrap break-words bg-gray-950 p-4 text-sm text-gray-100">
        <code dangerouslySetInnerHTML={{
    __html: highlightJson(response)
  }} />
      </pre>
      </div>
    </div>
    </details>;
};

<div className="api-operation-signature">
  `veryfront__invoke_agent`
</div>

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

| Field | Type | Required | Description and constraints |
| - | - | - | - |
| `prompt` | `string` | Yes | Required handoff prompt for the delegated run. |
| `task_id` | `string` | No | 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. Minimum length: `1`. Maximum length: `200`. |
| `context_mode` | `string` | No | 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. Values: `"continue"`, `"fresh"`. |
| `idempotency_scope` | `string` | No | 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. Values: `"durable_task"`. |
| `context` | `object` | No | 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. Default: `&#123;&#125;`. |
| `evidence_refs` | `object[]` | No | 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. |
| `description` | `string` | No | Optional short summary of the delegated task for UI and audit display. |
| `agent_id` | `string` | No | Optional agent id. Must be the exact id from agent discovery (e.g. [`list_agents`](/docs/cloud/mcp/tools/list-agents)), without any prefix or namespace. Defaults to the current agent. |
| `project_id` | `string` | No | Optional exact project UUID for cross-project delegation. Defaults to the current project. |
| `runtime_target_kind` | `string` | No | Optional exact runtime target override. Leave unset unless the user explicitly asked to switch targets. Values: `"main_branch"`, `"environment"`, `"preview_branch"`. |
| `target_environment_id` | `string` | No | Required only for a real environment target override and must be the exact environment UUID. |
| `target_branch_id` | `string` | No | Required only for a real preview branch override and must be the exact branch UUID. |
| `source_target_kind` | `string` | No | Optional 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_delegation` | `boolean` | No | Optional. When true, the child run may invoke [`invoke_agent`](/docs/cloud/mcp/tools/invoke-agent) again. Defaults to false for child runs. |
| `tools` | `string[]` | No | Optional exact allowlist of tool names for the child run. Omit to inherit all available tools. |
| `model` | `string` | No | Optional model override for the child run. Must be allowed by the target agent if restricted. |
| `thinking` | `boolean or integer` | No | 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. |
| `max_steps` | `integer` | No | Optional 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 title="input-schema.json" theme={null}
{
  "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](/docs/cloud/apis/agents) to configure the agent's tools. Start the agent through the [Execution API](/docs/cloud/apis/execution). The runtime supplies the execution context for this tool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.