Blueprints

Blueprints are JSON-serializable representations of agents, workflows, and conductors. They enable external tools to understand and reconstruct YosrAI components without exposing internal code.

Purpose

Use blueprints to: - Export agent/workflow configurations for visual builders - Version control complex setups - Deploy agents/workflows via API - Test with different configurations

Agent Blueprints

Exporting

from yosrai import Agent, tool

@tool
def calculate(x: int, y: int) -> int:
    return x + y

agent = Agent(
    name="Calculator",
    instructions="You are a math assistant.",
    tools=[calculate],
    model="openai/gpt-4o"
)

blueprint = agent.to_blueprint()
print(blueprint)
# {
#   "name": "Calculator",
#   "instructions": "You are a math assistant.",
#   "config": {"model": "openai/gpt-4o", ...},
#   "tools": [{"name": "calculate", "schema": {...}}]
# }

Reconstructing

reconstructed_agent = Agent.from_blueprint(blueprint)
result = reconstructed_agent.run("What is 5 + 3?")

Workflow Blueprints

Complex Workflow Export

from yosrai import Workflow, Agent

researcher = Agent(name="Researcher", instructions="Research topics")
writer = Agent(name="Writer", instructions="Write summaries")

workflow = Workflow("Pipeline")
workflow.start(researcher).then(writer)

blueprint = workflow.to_blueprint()
# Contains complete DAG with steps, conditions, agent references

Reconstruction with Agents

agents = {
    "researcher": researcher,
    "writer": writer
}
reconstructed = Workflow.from_blueprint(blueprint, agents=agents)

API Usage

Blueprints can be executed directly via the service API:

from yosrai import ServiceWrapper

service = ServiceWrapper(placeholder_agent)

# POST /run-blueprint
blueprint_data = {
    "type": "agent",
    "blueprint": blueprint,
    "input": "Hello"
}

result = service.run_blueprint_endpoint(blueprint_data)

Blueprint Schema

Agent Blueprint

{
  "name": "string",
  "instructions": "string",
  "config": {
    "model": "string",
    "max_loops": "integer",
    ...
  },
  "tools": [
    {
      "name": "string",
      "schema": {
        "type": "function",
        "function": {
          "name": "string",
          "parameters": {...}
        }
      }
    }
  ]
}

Workflow Blueprint

{
  "name": "string",
  "steps": [
    {
      "type": "agent_step",
      "agent": "agent_name",
      "name": "step_name"
    }
  ]
}

Conductor Blueprint

{
  "name": "string",
  "type": "Conductor",
  "instructions": "string",
  "skills": [
    {
      "type": "Agent",
      "name": "skill_agent_name",
      ...
    }
  ],
  "config": {
    "model": "string",
    "planning": true // New in v0.2.1
  }
}

Pipeline Blueprint

{
  "name": "string",
  "type": "Pipeline",
  "steps": [
    {
      "type": "Agent",
      "name": "step_1_agent",
      ...
    }
  ],
  "config": {
    "model": "string"
  }
}

API Reference

yosrai.engine.agents.agent.Agent.to_blueprint()

Serialize the Agent to a JSON-compatible blueprint.

Note: Tools are stored as their schemas only. When reconstructing, you must provide the actual tool functions via the tools parameter.

Returns:

Type	Description
Dict[str, Any]	Dict containing the agent's configuration.

yosrai.engine.agents.agent.Agent.from_blueprint(blueprint, tools=[], validate=True, **kwargs) classmethod

Reconstruct an Agent from a blueprint.

Parameters:

Name	Type	Description	Default
blueprint	Dict[str, Any]	The blueprint dict (from to_blueprint()).	required
tools	List[Callable]	List of actual tool functions to attach.	[]
validate	bool	Whether to validate the blueprint before reconstruction (default: True).	True
**kwargs	Any	Override any blueprint values (e.g., api_key).	{}

Returns:

Type	Description
Agent	A new Agent instance.

Raises:

Type	Description
BlueprintValidationError	If validation is enabled and the blueprint is invalid.

yosrai.engine.workflows.workflow.Workflow.to_blueprint()

Serialize the Workflow to a JSON-compatible blueprint.

Returns:

Type	Description
Dict[str, Any]	Dict containing the workflow's structure.

yosrai.engine.workflows.workflow.Workflow.from_blueprint(blueprint, agents={}, conditions={}, validate=True, event_manager=None, **kwargs) classmethod

Reconstruct a Workflow from a blueprint.

Parameters:

Name	Type	Description	Default
blueprint	Dict[str, Any]	The blueprint dict (from to_blueprint()).	required
agents	Dict[str, Agent]	Map of agent names to Agent instances.	{}
conditions	Dict[str, Callable]	Map of condition names to callable functions.	{}
validate	bool	Whether to validate the blueprint before reconstruction (default: True).	True
event_manager	Optional[EventManager]	Optional EventManager to share across steps.	None
**kwargs	Any	Additional workflow configuration.	{}

Returns:

Type	Description
Workflow	A new Workflow instance.

Raises:

Type	Description
BlueprintValidationError	If validation is enabled and the blueprint is invalid.

Note

For full reconstruction, you must provide the agents and conditions that were used in the original workflow.