Skip to main content

​
Overview

The agent_diagnose tool runs comprehensive diagnostics on agents to verify they are properly configured and responding correctly. Use it to troubleshoot integration issues or validate new agent setups.

​
When to Use Diagnostics

  • New agent setup - Validate configuration before using in campaigns
  • Integration issues - Troubleshoot connectivity or response problems
  • Periodic health checks - Monitor agent availability and compliance

​
Running Diagnostics

​
Basic Diagnostic

Agent: Call tool agent_diagnose with body: 
{
  "agentId": "agent_123"
}
This runs all checks: connection, tools, and responses.

​
Selective Checks

Run only specific checks: Agent: Call tool agent_diagnose with body: 
{
  "agentId": "agent_123",
  "checks": ["connection", "tools"]
}
Available check types:
  • connection - Endpoint reachability and latency
  • tools - ADCP tool presence validation
  • responses - Response format and content validation (SALES agents only)
  • all - Run all checks (default)

​
Verbose Mode

Include raw response data for debugging: Agent: Call tool agent_diagnose with body: 
{
  "agentId": "agent_123",
  "verbose": true
}

​
Understanding Results

The diagnostic returns factual results about what’s working and what’s not, along with a list of issues found.

​
Connection Check

Reports whether the endpoint is reachable and measures latency: 
{
  "connection": {
    "reachable": true,
    "latencyMs": 245
  }
}
If unreachable: 
{
  "connection": {
    "reachable": false,
    "error": "Connection refused: agent endpoint unreachable"
  }
}

​
Tools Check

Reports which required and recommended ADCP tools are present: 
{
  "tools": {
    "required": [
      { "name": "get_products", "present": true },
      { "name": "create_media_buy", "present": true },
      { "name": "update_media_buy", "present": true },
      { "name": "sync_creatives", "present": true }
    ],
    "recommended": [
      { "name": "list_authorized_properties", "present": true },
      { "name": "list_creative_formats", "present": false }
    ],
    "extra": ["custom_reporting_tool"]
  }
}

​
Response Validation (SALES Agents)

For SALES agents, validates get_products responses: 
{
  "responses": {
    "getInfo": {
      "responded": true,
      "agentName": "Example Publisher"
    },
    "getProducts": {
      "emptyBrief": { "responded": true, "productCount": 12 },
      "sampleBrief": { "responded": true, "productCount": 8 },
      "noBrandManifest": { "responded": true, "productCount": 12 },
      "schemaValid": true
    },
    "listAuthorizedProperties": {
      "available": true,
      "responded": true,
      "publisherCount": 5,
      "channels": ["display", "video"],
      "countries": ["US", "CA"]
    },
    "listCreativeFormats": {
      "available": false
    }
  }
}

​
Issues

Any problems found are listed in the issues array: 
{
  "issues": [
    "Missing required ADCP tools: sync_creatives. These tools are essential for SALES agent functionality.",
    "Products are missing Scope3-required fields: pricing_options. These fields are optional in ADCP but required for Scope3 campaign optimization."
  ]
}
An empty issues array means the agent passed all checks.

​
Agent Type Requirements

Different agent types have different required tools:

​
SALES Agents

Required:
  • get_products - Return available advertising products
  • create_media_buy - Create media buy orders
  • update_media_buy - Modify existing orders
  • sync_creatives - Attach creatives to orders
Recommended:
  • list_authorized_properties - List available inventory
  • list_creative_formats - Supported creative formats
  • list_creatives - List available creatives
  • get_media_buy_delivery - Delivery reporting

​
SIGNAL Agents

Required:
  • get_signals - Retrieve targeting signals
  • activate_signal - Enable signal for campaigns

​
OUTCOME Agents

Required:
  • accept_proposal - Accept outcome measurement proposals
  • get_outcome_status - Check measurement status

​
Common Issues

​
Connection Failed

Connection failed: Connection refused: agent endpoint unreachable
Check:
  • Agent endpoint URL is correct
  • Agent server is running
  • Network/firewall allows connections
  • Authentication credentials are valid

​
Missing Required Tools

Missing required ADCP tools: create_media_buy, sync_creatives
Check:
  • Agent implements all required ADCP tools
  • Tool names match ADCP specification exactly
  • Agent is returning tools in discovery response

​
Missing Scope3-Required Fields

Products are missing Scope3-required fields: pricing_options, format_ids
The ADCP client library validates standard schema fields. This check validates fields that Scope3 requires beyond the base spec. Check:
  • Product responses include Scope3-required fields: pricing_options, format_ids
  • These fields are optional in ADCP but required for Scope3 campaign optimization

​
High Latency

If connection latency exceeds 5 seconds: Check:
  • Agent server performance
  • Network routing between Scope3 and agent
  • Consider regional deployment

​
Best Practices

Run diagnostics after any agent configuration changes to verify the update was successful.
Use verbose mode when debugging issues - the raw responses often reveal the exact problem.
Diagnostics make actual calls to the agent endpoint. Avoid running excessively in production environments.

​
Next Steps

  • Set up sales agents for inventory access
  • Configure outcome agents for measurement
  • Monitor agent health through periodic diagnostics