Execution & Service

YosrAI provides transparent execution features and service deployment capabilities.

Transparent Execution

Verbose Mode

Enable step-by-step reasoning output:

from yosrai import Agent

agent = Agent(
    name="Assistant",
    instructions="Help users",
    verbose=True  # Shows execution steps
)

agent.run("Hello")
# Output:
# 🚀 Assistant started
# 💭 Thinking... done
# ✅ Assistant → Hello! How can I help?

Execution Tracing

Capture execution for replay and analysis:

# Capture execution
result = agent.run("Hello", trace=True)

# Result is ExecutionResult object
print(f"Duration: {result.duration_ms}ms")
print(f"Events: {len(result.events)}")

# Replay execution with timing
result.replay()

# Export trace as JSON
trace_data = result.to_dict()

Service Deployment

Basic Service

Deploy agents and workflows as REST APIs:

from yosrai import ServiceWrapper, Agent

agent = Agent(name="API Agent", instructions="Help users")
service = ServiceWrapper(agent, title="My Agent API")

# Run service (blocks)
service.run(host="0.0.0.0", port=8000)

API Endpoints

• GET /health - Health check
• GET /info - Service metadata and blueprint
• POST /run - Execute agent/workflow
• POST /run-blueprint - Execute from JSON blueprint
• GET /docs - Swagger UI (auto-generated)
• GET /openapi.json - OpenAPI specification

Request Formats

# Simple input
{"input": "Hello world"}

# Complex input
{
  "inputs": {
    "query": "What is AI?",
    "language": "English"
  }
}

# Blueprint execution
{
  "type": "agent",
  "blueprint": {...},
  "input": "Hello"
}

Response Formats

# Agent response
{"output": "Hello! How can I help?"}

# Workflow response (full context)
{
  "input": "Start",
  "agent1_output": "...",
  "agent2_output": "..."
}

Error Handling

YosrAI provides educational error messages:

from yosrai.engine.core.errors import YosraiError

try:
    agent.run("...")
except YosraiError as e:
    print(e)  # Message + suggestion + doc link
    e.rich_print()  # Formatted output with colors

API Reference

yosrai.engine.agents.agent.Agent.run(input_data, response_model=None, stream=False, trace=False)

Run the agent loop (Sync).

Parameters:

Name	Type	Description	Default
input_data	Union[str, Context]	User query string or full Context object.	required
response_model	Any	Optional Pydantic model for structured output.	None
stream	bool	Whether to stream tokens to callbacks.	False
trace	bool	If True, return ExecutionResult with replay() capability.	False

Note

After calling run(), access usage via agent.last_usage:

result = agent.run("Hello") print(f"Cost: ${agent.last_usage.cost:.4f}")

yosrai.engine.workflows.workflow.Workflow.run(context=None, start_step=0, trace=False, resume_path=None, **kwargs)

Run the workflow with the given initial inputs.

Parameters:

Name	Type	Description	Default
context	Optional[Union[Context, str]]	Optional Context object, or a string to use as 'input'.	None
start_step	int	Step index to start execution from (default 0).	0
trace	bool	If True, return ExecutionResult with replay() capability.	False
resume_path	Optional[List[int]]	Optional list of step indices for nested resumption.	None
**kwargs	Any	Initial inputs if context is not provided (or to update it).	{}

Note

After calling run(), access usage via workflow.last_usage:

result = workflow.run(input="Hello") print(f"Total cost: ${workflow.last_usage.cost:.4f}")

yosrai.engine.core.events.ExecutionResult

Captures the result of an Agent or Workflow execution with replay capability.

Attributes:

Name	Type	Description
value		The actual return value (string, structured output, etc.)
events		List of WorkflowEvents captured during execution.
duration_ms		Total execution time in milliseconds.
usage		Usage tracking information (tokens/cost).

replay(delay=0.0)

Replay the execution step-by-step with timing information.

Parameters:

Name	Type	Description	Default
delay	float	Optional delay between events (seconds) for dramatic effect.	0.0

to_dict()

Export execution trace as a dictionary.

yosrai.engine.service.service.ServiceWrapper

Wraps a Workflow or Agent into a FastAPI service with OpenAPI documentation.

Features: - /health - Health check - /info - Service info with blueprint export - /run - Execute the agent/workflow - /run-blueprint - Execute a blueprint directly - /docs - Swagger UI (auto-generated) - /openapi.json - OpenAPI spec

run(host='0.0.0.0', port=8000)

Run the service using Uvicorn.