`invarium_get_agent`

Get detailed information about a specific agent. Returns tools, constraints, AQS score with trend, recent test runs, and a dashboard link.

When to Use

Call invarium_get_agent when you need to inspect a specific agent’s current state. Common scenarios:

After syncing test results, to see the updated AQS score and trend
Before generating new tests, to review the agent’s tools and constraints
When diagnosing test failures, to check the agent’s configuration
To get a quick link to the agent’s dashboard page

See Agent Quality Score for details on how AQS is calculated and how to interpret trends.

Parameters

Name	Type	Required	Default	Description
`agent_name`	`string`	Yes	—	Name of the agent to look up. Must match the name used when the blueprint was uploaded.

invarium_get_agent

Get detailed information about a specific agent. Returns tools, constraints, AQS score, recent test runs, and a dashboard link.

Parameters

Name	Type	Required	Description
`agent_name`	string	required	Name of the agent to look up.

Returns

Formatted agent details including status, AQS score with trend, tools, constraints, recent test runs, and dashboard link.

Example

Agent: customer-support-agent
Status: ACTIVE
Description: Handles customer inquiries via chat
AQS Score: 78/100 (↑ +5)

Tools (3):
  - search_tickets: Search support tickets by keyword
  - create_ticket: Create a new support ticket
  - escalate_to_human: Transfer conversation to a human agent

Constraints (2):
  - Never share internal ticket IDs with customers
  - Escalate billing disputes to a human agent

Recent test runs: 3 completed, 1 running
Last run: 2 hours ago (passed: 8, failed: 2)

View on dashboard: https://app.invarium.dev/agent/ag_abc123

Response

The tool returns a formatted text block with the agent’s full details:

Agent: customer-support-agent
Status: ACTIVE
Description: Handles customer inquiries via chat
AQS Score: 78/100 (↑ +5)

Tools (3):
  - search_tickets: Search support tickets by keyword
  - create_ticket: Create a new support ticket
  - escalate_to_human: Transfer conversation to a human agent

Constraints (2):
  - Never share internal ticket IDs with customers
  - Escalate billing disputes to a human agent

Recent test runs: 3 completed, 1 running
Last run: 2 hours ago (passed: 8, failed: 2)

View on dashboard: https://app.invarium.dev/agent/ag_abc123

Response Fields

Field	Description
Agent	The agent’s registered name.
Status	Current status: `ACTIVE`, `INACTIVE`, or `UNKNOWN`.
Description	The agent’s description from its blueprint.
AQS Score	Agent Quality Score (0—100) with trend indicator. See below.
Tools	List of registered tools with their descriptions.
Constraints	List of behavioral constraints and guardrails.
Recent test runs	Summary of recent test runs by status (completed, running, etc.).
Last run	When the most recent test run happened and its pass/fail counts.
Dashboard link	Direct URL to the agent’s page on the Invarium dashboard.

AQS Score and Trend

The AQS (Agent Quality Score) reflects the agent’s overall behavioral quality based on test results. The trend indicator shows the change since the previous measurement:

Display	Meaning
`78/100`	Current score, no trend data available yet.
`78/100 (↑ +5)`	Score improved by 5 points since the last measurement.
`78/100 (↓ -3)`	Score decreased by 3 points since the last measurement.
`--`	No test runs have been completed yet. AQS is not available until the first test cycle.

Examples

Basic Usage

Look up a specific agent by name:

"Show me details for my customer-support-agent."

After Syncing Results

Check the updated AQS score after syncing test results:

"Sync these results for customer-support-agent, then show me its updated AQS score."

Reviewing Before Test Generation

Check the agent’s current tools and constraints before generating new tests:

"Show me the tools and constraints for my travel-booking-agent before I generate new tests."

Error Responses

Error	Cause	Fix
`Authentication failed: invalid API key`	Invalid or missing API key.	Verify your `INVARIUM_API_KEY`. Run `invarium_connect` first.
`Agent '{name}' not found. Upload a blueprint first with invarium_upload_blueprint.`	No agent with this name exists in your workspace.	Check the agent name. Use `invarium_list_agents` to see all registered agents.
`Failed to get agent: ...`	Backend API error.	Check the error details and try again.

See Error Codes for the full error reference.

Was this page helpful?

invarium_upload_blueprint invarium_list_agents