Skip to main content

Phoenix Agent Tools

Tools for discovering and invoking Phoenix AI agents via MCP.

Overview​

Phoenix provides three tools for external clients to interact with AI agents:

  • phoenix_list_agents - List available agents
  • phoenix_invoke_agent - Execute an agent
  • phoenix_get_run_status - Check run status and get artifacts

All operations are scoped to the authenticated organization.

phoenix_list_agents​

List all published agents available for the authenticated organization.

Parameters​

This tool takes no parameters.

Example Usage​

{
  "tool": "phoenix_list_agents",
  "parameters": {}
}

Response​

{
  "data": {
    "agents": [
      {
        "id": "agent_instance_123",
        "name": "Company Research Agent",
        "description": "Researches companies and generates reports",
        "version": "v1.2",
        "tools": ["company_firmographic", "company_technographic", "web_search"],
        "inputs": {
          "company_domain": { "type": "string", "required": true },
          "depth": { "type": "string", "enum": ["basic", "detailed"] }
        }
      }
    ],
    "count": 1
  }
}

phoenix_invoke_agent​

Execute a Phoenix agent with specified inputs.

Parameters​

NameTypeRequiredDescription
agent_idstringYesAgent instance ID from phoenix_list_agents
inputsobjectYesInput parameters for the agent
paramsobjectNoOptional execution parameters

Example Usage​

{
  "tool": "phoenix_invoke_agent",
  "parameters": {
    "agent_id": "agent_instance_123",
    "inputs": {
      "company_domain": "salesforce.com"
    },
    "params": {
      "depth": "detailed",
      "output_formats": ["html", "pdf"]
    }
  }
}

Response​

{
  "data": {
    "runId": "run_abc123",
    "status": "running",
    "message": "Agent run started successfully. The run will be processed asynchronously."
  }
}

Possible Statuses​

StatusDescription
queuedRun is waiting to start
runningRun is in progress
succeededRun completed successfully
partially_failedRun completed with some failures
failedRun failed

phoenix_get_run_status​

Get the status and details of an agent run.

Parameters​

NameTypeRequiredDescription
run_idstringYesRun ID from phoenix_invoke_agent

Example Usage​

{
  "tool": "phoenix_get_run_status",
  "parameters": {
    "run_id": "run_abc123"
  }
}

Response​

{
  "data": {
    "runId": "run_abc123",
    "status": "succeeded",
    "agentName": "Company Research Agent",
    "inputs": {
      "company_domain": "salesforce.com"
    },
    "startedAt": "2025-02-05T12:00:00Z",
    "finishedAt": "2025-02-05T12:05:30Z",
    "artifacts": [
      {
        "id": "artifact_1",
        "type": "html",
        "url": "https://phoenix.hginsights.com/artifacts/..."
      },
      {
        "id": "artifact_2",
        "type": "pdf",
        "url": "https://phoenix.hginsights.com/artifacts/..."
      }
    ],
    "costSummary": {
      "tool_credits": 5,
      "llm_credits": 10,
      "total_credits": 15
    }
  }
}

Required Integrations​

These tools do not require external integrations - they use internal Phoenix data.

Workflow Example​

1. List available agents
   → phoenix_list_agents

2. Choose an agent and invoke it
   → phoenix_invoke_agent with agent_id and inputs

3. Poll for completion
   → phoenix_get_run_status with run_id

4. Download artifacts when succeeded
   → Use artifact URLs from response

Error Handling​

Common errors:

  • Agent not found: Check agent_id from phoenix_list_agents
  • Run not found: Check run_id from phoenix_invoke_agent
  • Invalid inputs: Check agent's input schema
  • Agent not published: Only published agents can be invoked

Annotations​

These tools include MCP annotations:

  • phoenix_list_agents: readOnlyHint, idempotentHint
  • phoenix_invoke_agent: openWorldHint (may call external APIs)
  • phoenix_get_run_status: readOnlyHint, idempotentHint

Next Steps​