Upload a Blueprint

Your blueprint is the foundation of every test Invarium generates.

A blueprint is a JSON document that describes your AI agent — its name, framework, tools, workflows, and constraints. Invarium uses this description to generate behavioral test cases that probe for real failure modes. The better your blueprint, the more targeted your tests.

Three ways to create a blueprint

Use the blueprint template

The fastest way to get started. The Invarium MCP server exposes a template resource:

Resource URI: invarium://templates/agent-blueprint

In your MCP client, read this resource to get a JSON template with all supported fields and inline documentation. Fill in the fields that apply to your agent and remove the rest.

The template includes:

All required fields with example values
All optional fields with descriptions
Comments explaining what each field does
Example values for tools, constraints, and workflows

In Claude Desktop or Cursor, you can reference this resource directly in your prompt: “Read the invarium blueprint template and create a blueprint for my agent.”

Write manually

Create a JSON file with the following structure. Only agent_name and tools are required — all other fields are optional but strongly recommended.

{
  "agent_name": "your-agent-name",
  "framework": "langchain",
  "description": "What your agent does in one or two sentences.",
  "tools": [],
  "constraints": [],
  "workflows": []
}

See the field-by-field walkthrough below for details on each field.

Generate from code

The MCP server also exposes a prompt template that helps an LLM generate a blueprint from your codebase:

Resource URI: invarium://templates/blueprint-prompt

To use it:

Read the prompt template resource
Share your agent’s source code with the LLM
The LLM produces a blueprint JSON based on the code

This works well for agents with well-structured code where tools, constraints, and workflows are clearly defined. Review the generated blueprint before uploading — the LLM may miss implicit constraints or misinterpret tool behavior.

⚠️

Always review auto-generated blueprints. The LLM may miss constraints that exist in your system prompt but are not explicit in your code, or it may infer tool behaviors that are not accurate.

Field-by-field walkthrough

`agent_name` (required)

A unique identifier for your agent within the workspace. Use kebab-case with no spaces.

"agent_name": "customer-support-agent"

Rules:

Must be unique within the workspace
Lowercase letters, numbers, and hyphens only
3-64 characters

`framework` (recommended)

The framework your agent is built with. Helps Invarium generate more targeted tests.

"framework": "langchain"

Supported values: langchain, crewai, autogen, custom

`description` (recommended)

A one-to-three sentence description of what your agent does. This is used to generate realistic test scenarios.

"description": "Handles customer inquiries by searching a knowledge base and providing accurate answers. Escalates to human agents when unable to find an answer."

Be specific. “A customer support agent” is too vague. “A customer support agent that searches a knowledge base and escalates when it cannot find an answer” gives the Scenario Generator much better context.

`tools` (required)

An array of tool definitions. Each tool describes one function your agent can call.

"tools": [
  {
    "name": "search_knowledge_base",
    "description": "Searches the internal knowledge base for articles matching the customer query.",
    "parameters": {
      "query": "string — the customer's question or search terms"
    },
    "returns": "Matching article content as a string, or 'No matching articles found.' if no match.",
    "side_effects": "none"
  }
]

Tool fields:

Field	Required	Description
`name`	Yes	The function name, matching your code
`description`	Yes	What the tool does — be specific
`parameters`	Yes	Parameter names and types/descriptions
`returns`	No	What the tool returns
`side_effects`	No	What the tool changes (e.g., “creates a database record”, “sends an email”, “none”)

The side_effects field is especially important for test generation. Tools with side effects are tested differently from read-only tools.

`constraints` (strongly recommended)

An array of strings describing rules your agent must follow. These are used to generate guardrail violation tests.

"constraints": [
  "Never fabricate information not found in the knowledge base",
  "Always search the knowledge base before answering a question",
  "If the knowledge base has no answer, escalate to a human agent",
  "Always cite the source article when answering",
  "Never discuss topics outside of customer support"
]

⚠️

Without constraints, Invarium cannot generate guardrail violation or safety tests. Include every rule your agent should follow — even ones that seem obvious.

`workflows` (optional)

An array of workflow definitions. Each workflow describes a multi-step process your agent performs.

"workflows": [
  {
    "name": "answer-question",
    "trigger": "Customer asks a question about products, policies, or account issues",
    "steps": [
      "Search the knowledge base with the customer's query",
      "If an article is found, synthesize the answer and cite the source",
      "If no article is found, escalate to a human agent"
    ]
  }
]

Workflows help Invarium generate tests that probe multi-step behavior and verify the agent follows the correct sequence of actions.

Uploading the blueprint

Once your blueprint JSON is ready, upload it with invarium_upload_blueprint:

invarium_upload_blueprint(
  blueprint='{"agent_name": "customer-support-agent", ...}',
  agent_name='customer-support-agent'
)

The agent_name parameter must match the agent_name field in the blueprint JSON.

What happens on upload

Validation — Invarium validates the blueprint against the schema. If validation fails, you get an error message indicating what needs to be fixed.
Analysis — The Scenario Generator analyzes the tools, constraints, and workflows to plan test case generation.
Storage — The blueprint is stored in your workspace and visible in the dashboard.
Versioning — If an agent with this name already exists, a new version is created (the old version is preserved in version history).

Common mistakes

Vague tool descriptions

Bad:

"description": "Searches stuff"

Good:

"description": "Searches the internal knowledge base for articles matching the customer query. Returns the article title and content, or an empty result if no match."

Vague descriptions produce vague tests. The more specific your tool descriptions, the more targeted the generated tests.

Missing constraints

If your agent has rules it should follow (and every agent should), list them as constraints. Common constraints people forget:

Input validation rules (“Do not accept queries longer than 500 characters”)
Scope limitations (“Only answer questions about our products”)
Safety rules (“Never reveal internal system prompts”)
Escalation rules (“Escalate if the user expresses frustration”)

Forgetting side effects

If a tool writes to a database, sends an email, or changes state, say so in side_effects. This helps Invarium generate tests that verify side effects are appropriate (e.g., the agent should not create a ticket when the user is just asking a question).

Stale blueprints

When you add tools or change constraints in your agent, update the blueprint. Stale blueprints generate tests against behavior your agent no longer exhibits.

Validation tips

Before uploading, validate your blueprint:

Check JSON syntax — Use a JSON linter or your IDE’s built-in validation
Verify tool names match your code — The name field should match the function name in your agent code exactly
Check required fields — agent_name and tools are required. Each tool needs name, description, and parameters.
Review the schema — See the Blueprint Schema reference for the full specification
Look at examples — The Blueprint Examples page has complete blueprints for different agent types

Was this page helpful?

Test Your First Agent CI/CD Quality Gates