Skip to main content

Invoke Phoenix Agent

Coming soon

The v2 MCP API is in preview and not yet generally available. These pages document its tools and request/response shapes; live data access is limited to enrolled organizations until v2 is released.

Start a Phoenix AI agent run with the given inputs. This kicks off one of THIS org's published orchestration agents (e.g. an Account Research Brief that assembles a cited deliverable) — it does not itself return company data; it produces a run whose artifact you retrieve later. Returns a run id (UUID); the run executes asynchronously and can take several minutes. After invoking, do NOT repeatedly poll for status — check phoenix_get_run_status at most once or twice; if the run is still queued or running, tell the user the deliverable is generating and give them the run id to check later. Only keep polling if the user explicitly asks you to wait. Use this when the user wants to actually run an agent/generate a deliverable. Do NOT use this to see which agents exist or find an agent_id — use phoenix_list_agents; do NOT use it to check on or fetch the result of an already-started run — use phoenix_get_run_status.

Parameters​

NameTypeRequiredDefaultDescription
agent_idstring✅ Yes-The agent instance id to run (UUID). Get it from phoenix_list_agents — this is the id field of an agent row, not its name.
inputsobject✅ Yes-The agent's input object, shaped by that agent's input schema (see the inputs field from phoenix_list_agents). Keys vary by agent — e.g. an Account Research Brief takes { domain, hgid?, depth? }.
paramsobject❌ No-Optional execution/output controls independent of the agent's inputs (e.g. { depth: "deep", output_formats: ["html","pdf"] }). Omit to use the agent's defaults.

Use Cases​

  • Generate an Account Research Brief for a target company by domain
  • Kick off a published agent workflow and hand the run id back to the user
  • Run an agent at a deeper research depth via the params object
  • Start a deliverable an AE can open before a discovery call

Example Usage​

Run an Account Research Brief by domain

{
  "tool": "phoenix_invoke_agent",
  "arguments": {
    "agent_id": "00000000-0000-0000-0000-000000000000",
    "inputs": {
      "domain": "siemens.com"
    }
  }
}

Run at deep research depth

{
  "tool": "phoenix_invoke_agent",
  "arguments": {
    "agent_id": "00000000-0000-0000-0000-000000000000",
    "inputs": {
      "domain": "acme.com"
    },
    "params": {
      "depth": "deep"
    }
  }
}

phoenix_list_agents, phoenix_get_run_status, phoenix_list_artifacts, phoenix_get_artifact