02.5 results

Results

Every execution in BindAI returns a result object.

Result objects provide a consistent way to determine whether an operation succeeded, inspect its output, or handle errors.

Instead of returning raw strings or provider-specific responses, BindAI returns structured result types across the framework.

---

Why Results?

Using result objects provides several advantages:

• consistent API
• predictable error handling
• structured outputs
• provider independence
• easier debugging

Applications can always check the success state before using the output.

---

AgentResult

The most common result type is AgentResult.

Every agent execution returns one.

result = agent.chat(
    "Explain BindAI."
)

Example:

print(result.success)

print(result.output)

---

AgentResult Structure

AgentResult(
    success=True,
    output="BindAI is an AI framework.",
    error=None,
)

Fields:

Field	Description
success	Indicates whether execution completed successfully
output	The final response produced by the agent
error	Error information when execution fails

---

Checking Success

Always verify that execution completed successfully.

result = agent.chat(
    "Hello"
)

if result.success:
    print(result.output)
else:
    print(result.error)

This avoids application crashes caused by failed executions.

---

Handling Errors

When an execution fails:

AgentResult(
    success=False,
    output=None,
    error="Provider timeout"
)

Applications can inspect the error without relying on exceptions from individual providers.

---

Structured Output

If an output model is supplied, the result contains the parsed object.

result = agent.chat(
    "Create a user profile.",
    output=UserProfile,
)

Example:

profile = result.output

print(profile.name)

Instead of raw text, output contains an instance of the requested model.

---

Workflow Results

Workflow execution also returns a result object.

Example:

result = workflow.execute()

The output typically contains the workflow variables collected during execution.

print(result.output)

Example output:

{
    "summary": "...",
    "approved": True,
}

---

Tool Results

Tools also return structured results.

Example:

ToolResult(
    success=True,
    output="Search completed.",
    error=None,
)

This allows workflows and agents to process tool responses consistently.

---

Human Task Results

Human approval nodes store their completion result inside the workflow context.

Example:

task.result = {
    "approved": True
}

The workflow can use this information after resuming execution.

---

Success Pattern

Most BindAI result objects follow the same structure.

Success

↓

Output

↓

Error

This consistency makes it easy to compose agents, tools, and workflows together.

---

Exceptions vs Results

BindAI prefers returning result objects for expected execution outcomes.

Exceptions are generally reserved for unexpected failures such as:

• programming errors
• invalid configuration
• missing dependencies

Operational failures are represented through result objects whenever possible.

---

Debugging

Result objects are useful during development.

Example:

print(result.success)

print(result.output)

print(result.error)

This provides immediate visibility into execution without inspecting provider responses.

---

Best Practices

• Always check success before using output.
• Display error messages to assist debugging.
• Use structured outputs whenever possible.
• Return consistent result objects from custom tools.
• Avoid returning raw provider responses directly to application code.

---

Summary

Result objects provide a unified interface for execution outcomes throughout BindAI.

Whether working with agents, tools, or workflows, developers interact with the same predictable success/error model, making applications easier to build, test, and maintain.