`invarium_upload_blueprint`

Upload an agent blueprint to the Invarium dashboard. Creates or updates the agent registration, detects tools and workflows, computes confidence, and triggers a server-side Agent Readiness Audit.

When to Use

Call invarium_upload_blueprint after reviewing the blueprint with invarium_prepare_blueprint and confirming you are ready to submit. This tool sends the blueprint to the Invarium backend, which:

Registers the agent (or updates the existing registration if one matches the agent name)
Detects tools and workflow chains
Triggers a server-side Agent Readiness Audit
Uploads an agent intelligence graph if one is included

After uploading, call invarium_get_audit to retrieve the full server-side audit results.

⚠️

Always call invarium_prepare_blueprint first to validate and preview. Only call this tool after the user has reviewed the preview and confirmed they want to submit.

See Create and Upload a Blueprint for the end-to-end workflow.

Parameters

Name	Type	Required	Default	Description
`blueprint`	`string`	Yes	—	YAML string of the agent blueprint. Same format as passed to `invarium_prepare_blueprint`.
`agent_name`	`string`	No	`null`	Agent name override. If omitted, the name is extracted from the `agent_name` or `name` field in the blueprint YAML.

invarium_upload_blueprint

Upload an agent blueprint to the Invarium dashboard. Call invarium_prepare_blueprint first to validate and preview. Only call this tool after the user has reviewed the preview and confirmed they want to submit.

Parameters

Name	Type	Required	Description
`blueprint`	string	required	YAML string of the agent blueprint.
`agent_name`	string \| null	default: null	Agent name. If not provided, extracted from the blueprint.

Returns

Confirmation with tool count, workflow chains, confidence level, dashboard link, and local audit preview.

Example

Blueprint uploaded for customer-support-agent ✓
Tools detected: 3
Workflow chains: 2
Confidence: high
View on dashboard: https://app.invarium.dev/agent/ag_abc123

Local Audit Preview: 82/100 (Green)
  3 finding(s) -- run invarium_get_audit for the server-side results

Update .invarium/config.json to add: "agent_id": "ag_abc123"

Response

On success, the tool returns a formatted confirmation:

Blueprint uploaded for customer-support-agent ✓
Tools detected: 3
Workflow chains: 2
Confidence: high
View on dashboard: https://app.invarium.dev/agent/ag_abc123

Local Audit Preview: 82/100 (Green)
  3 finding(s) -- run invarium_get_audit for the server-side results

Update .invarium/config.json to add: "agent_id": "ag_abc123"

If the agent already exists, the response says Blueprint updated for ... instead.

Field	Description
Tools detected	Number of tools found in the blueprint.
Workflow chains	Number of workflow chains identified.
Confidence	Blueprint completeness level: `high`, `medium`, or `low`.
Dashboard link	Direct URL to the agent’s page on the Invarium dashboard.
Local Audit Preview	Quick ARS score from a local audit run. The server-side audit (retrieved via `invarium_get_audit`) is authoritative.
Graph uploaded	Shown if the blueprint includes a graph. Displays the graph version number.

Create vs. Update

If an agent with the same name already exists in your workspace, invarium_upload_blueprint updates the existing registration. Previous test runs, scenarios, and audit history are preserved — only the blueprint definition is replaced.

Confidence Scoring

Confidence	Meaning
High	Blueprint includes tools, workflow chains, and constraints (or guardrails). Invarium can generate highly targeted tests.
Medium	Blueprint includes tools and either workflow chains or constraints, but not both. Tests will be generated but may be less targeted.
Low	Blueprint has tools only, or is missing tools entirely. Invarium will generate generic behavioral tests. Adding workflow chains and constraints will improve test quality.

Examples

Basic Usage

Upload a validated blueprint:

"Upload this blueprint for my customer-support-agent."

With Agent Name Override

"Upload this blueprint and register it as my travel-booking-agent."

Full Workflow: Prepare, Review, Upload

"Preview this blueprint for me before I upload it."

After reviewing:

"Looks good, go ahead and upload it."

Then to retrieve the server-side audit:

"Get the audit results for my customer-support-agent."

Validation Rules

The blueprint is validated before upload. The following rules apply:

agent_name is required (either in the blueprint YAML or as the agent_name parameter)
Each tool must have a name and description
framework (if provided) must be one of: langchain, crewai, autogen, openai_agents, openai, custom
side_effects on tools (if provided) must be an array containing any of: database_write, database_read, api_call, email_send, file_write, file_read, payment, notification, none
error_handling on tools (if provided) must be one of: retry, fallback, none
tools must be an array (if present)
workflow.chains must be an array (if present), and each chain must have a name
constraints must be an object or array (if present)

If validation fails, the error message indicates which field is invalid and what values are accepted.

Error Responses

Error	Cause	Fix
`Authentication failed: invalid API key`	Invalid or missing API key.	Verify your `INVARIUM_API_KEY`. Run `invarium_connect` first.
`Blueprint is not valid YAML: ...`	The `blueprint` string is not parseable YAML.	Check for syntax errors. Regenerate the blueprint if needed.
`Missing agent_name. Provide it as a parameter or include it in the blueprint.`	No agent name in the blueprint or parameter.	Add `agent_name` to the blueprint YAML or pass it as the `agent_name` parameter.
`Blueprint validation failed: ...`	Schema validation errors.	Fix the listed errors. See Blueprint Schema.
`Upload failed: ...`	Backend API rejected the request.	Check the error details. The agent may have reached a workspace limit.
`Blueprint too large`	The blueprint YAML exceeds the maximum size (500 KB).	Reduce the blueprint size — consider splitting into multiple agents if needed.

See Error Codes for the full error reference.

Was this page helpful?

invarium_prepare_blueprint invarium_get_agent