Results

BindAI uses AgentResult as the primary result object for completed agent execution. The result abstraction keeps application code independent from provider-specific response objects and provides a consistent way to access:

Execution status
Generated output
Execution error information when a failed result is returned

Streaming execution is different: streaming returns incremental provider output rather than a completed AgentResult.

AgentResult

A completed agent execution returns an AgentResult.

result = agent.run("Explain what BindAI is.")

print(result.output)

The public result type is:

from dataclasses import dataclass
from typing import Any


@dataclass(slots=True)
class AgentResult:
    success: bool
    output: Any = None
    error: str | None = None

The three application-facing fields are:

Field	Type	Description
`success`	`bool`	Whether the execution completed successfully.
`output`	`Any`	Generated output from the execution.
`error`	`str \| None`	Error information when a failed result contains an error.

For example:

result = agent.run("What is BindAI?")

print(result.success)
print(result.output)
print(result.error)

For successful results, error is normally None.

Accessing the Output

The generated response is available through result.output.

result = agent.run("What is BindAI?")

print(result.output)

For normal text generation, the output is the generated response text. For structured output, the output can instead be an instance of the requested output type. The exact Python type of output therefore depends on how the agent was executed.

Checking Execution Status

Use result.success when application behavior depends on whether execution completed successfully.

result = agent.run("Hello!")

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

A successful result has:

result.success is True

A failed AgentResult has:

result.success is False

When a failed result contains an error message, it is available through:

result.error

Applications should not assume that every possible execution failure is converted into an AgentResult. Some execution paths can raise Python exceptions instead.

Structured Output

BindAI supports structured output through the output parameter of run(). For example:

from pydantic import BaseModel

from bindai import Agent


class Person(BaseModel):
    name: str
    age: int


agent = (
    Agent.builder()
    .name("person-generator")
    .model("openai:gpt-4.1-mini")
    .instructions("Generate fictional people.")
    .build()
)

result = agent.run(
    "Generate a fictional person.",
    output=Person,
)

print(result.output)

When structured output succeeds, result.output contains the constructed output object. For example:

person = result.output

print(person.name)
print(person.age)

Structured Output Processing

The execution layer processes structured output after receiving the model response. The current execution path:

Gets the model response text.
Parses the response as JSON.
Passes the resulting dictionary to the requested output type.
Returns the constructed object when conversion succeeds.
Falls back to the raw response text when conversion fails.

Conceptually:

Model response
      |
      v
    JSON
      |
      v
Output type
      |
      +---- success ----> structured object
      |
      +---- failure ----> raw response text

For example, if the requested type is:

class Task:
    ...

the execution layer attempts the equivalent of:

data = json.loads(response)
structured = Task(**data)

The exact construction behavior depends on the output type supplied by the application. Provider and model behavior still matters because the model must produce output that can be interpreted as the requested structure.

Structured Output Fallback

Structured-output conversion does not guarantee that the final output will always be an instance of the requested type. If JSON parsing or output construction fails, the execution layer falls back to the original response text. Therefore, applications should consider checking the output type when the distinction matters:

result = agent.run(
    "Generate a fictional person.",
    output=Person,
)

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

Applications that require strict structured output should validate the resulting object before using it as structured application data.

Inspecting Result Information

During development, inspect the result object directly:

result = agent.run("Hello!")

print(type(result))
print(result)
print(result.success)
print(result.output)
print(result.error)

You can also inspect the public result type:

from bindai import AgentResult

print(AgentResult)
print(AgentResult.__annotations__)

This can be useful when developing against a specific BindAI release.

Handling Execution Failures

Agent execution can encounter failures such as:

Missing provider configuration
Invalid credentials
Unsupported model configuration
Network failures
Provider errors
Tool execution failures
Maximum tool iteration failures
Other execution errors

Applications should distinguish between a failed AgentResult and a Python exception. A failed result can be handled with:

result = agent.run("Hello!")

if result.success:
    print(result.output)
else:
    print(f"Agent execution failed: {result.error}")

When an execution path raises an exception, handle it normally:

try:
    result = agent.run("Hello!")
except Exception as exc:
    print(f"Agent execution raised an exception: {exc}")
else:
    if result.success:
        print(result.output)
    else:
        print(result.error)

For production applications, catch specific exception types when the application needs to distinguish between different failure categories.

Results and Exceptions

AgentResult and Python exceptions represent different execution outcomes. A result represents an execution path that returned an AgentResult. An exception interrupts normal execution and is handled through Python exception handling. For example:

try:
    result = agent.run("Hello!")
except Exception as exc:
    print(f"Execution failed: {exc}")
else:
    if result.success:
        print(result.output)
    else:
        print(result.error)

Do not assume that every provider or execution failure will be converted into:

AgentResult(
    success=False,
    error="...",
)

The exact failure behavior depends on the execution path involved.

Tool Results

Tool results are separate from the final AgentResult. A tool can return an ordinary Python value:

from bindai import tool


@tool
def add(a: int, b: int):
    return a + b

When the agent invokes the tool, its result becomes part of the agent execution flow. Conceptually:

Agent
  |
  v
Model
  |
  v
Tool
  |
  v
Tool result
  |
  v
Agent execution
  |
  v
AgentResult

The tool result is not itself the final agent result. The execution layer converts tool output into messages that are supplied back to the model when additional model execution is required. Tool execution events also expose whether the tool execution succeeded.

Tool Execution Failures

Tool failures can affect the overall agent execution. For example, the execution layer can receive a tool result containing an error and pass that information back into the model execution flow. Applications should therefore distinguish between:

The value returned by an individual tool.
The model response generated after tool execution.
The final AgentResult returned by the agent.

For advanced tool execution behavior, use the BindAI Tool API.

Maximum Tool Iterations

Agent execution can perform multiple model/tool turns. The agent configuration includes:

max_tool_iterations

The default value is:

If execution continues beyond the configured maximum, the execution path can fail with a maximum-tool-iterations error. For example:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .max_tool_iterations(5)
    .build()
)

This setting limits repeated tool-calling cycles.

Workflow Results

Workflow execution has its own result and data flow. Workflow nodes can produce values that are passed to later nodes, and a workflow can expose its own execution result. For example:

result = workflow.run()

print(result)

Workflow results should be handled according to the workflow API. Do not assume that a workflow result has the same fields as AgentResult. In particular:

AgentResult
    |
    +---- success
    +---- output
    +---- error

should not be treated as the universal result structure for every BindAI subsystem.

Result Flow

The general completed-agent result flow is:

Agent execution
      |
      v
Provider response
      |
      v
Result processing
      |
      v
AgentResult
      |
      +---- success
      |
      +---- output
      |
      +---- error

For normal text execution:

Provider response
      |
      v
AgentResult.output

For successful structured output:

Provider response
      |
      v
JSON parsing
      |
      v
Output type construction
      |
      v
AgentResult.output

For unsuccessful structured conversion:

Provider response
      |
      v
JSON/construction failure
      |
      v
Raw response
      |
      v
AgentResult.output

Results and Structured Applications

Structured results are useful when agent output is consumed directly by application code. For example:

from pydantic import BaseModel

from bindai import Agent


class Task(BaseModel):
    title: str
    priority: int


agent = (
    Agent.builder()
    .name("task-generator")
    .model("openai:gpt-4.1-mini")
    .instructions("Generate structured tasks.")
    .build()
)

result = agent.run(
    "Create a task for reviewing documentation.",
    output=Task,
)

if result.success:
    task = result.output

    print(task.title)
    print(task.priority)
else:
    print(result.error)

When structured conversion succeeds, downstream code can work with the resulting Python object instead of manually parsing generated text. Applications should still account for the possibility that structured conversion falls back to the raw response.

Results from Streaming

Streaming execution differs from standard run() execution. For example:

for chunk in agent.stream_chat("Explain neural networks."):
    print(chunk)

Streaming returns incremental output from the configured provider rather than waiting for a completed AgentResult. The streaming execution path calls the provider’s stream() method. Conceptually:

Agent
  |
  v
Provider.stream()
  |
  v
Stream iterator
  |
  +---- chunk
  +---- chunk
  +---- chunk
  +---- ...

Use standard run() when the application needs a completed AgentResult. Use streaming when the application needs to process or display model output progressively.

Result Handling in Applications

A typical application can handle a completed result like this:

result = agent.run("Explain what BindAI is.")

if result.success:
    print("Agent response:")
    print(result.output)
else:
    print("Agent execution failed:")
    print(result.error)

When the operation can raise exceptions, combine result handling with exception handling:

try:
    result = agent.run("Explain what BindAI is.")
except Exception as exc:
    print(f"Agent execution failed: {exc}")
else:
    if result.success:
        print(result.output)
    else:
        print(result.error)

This keeps application-level result handling independent from provider-specific response objects.

Keeping Provider Responses Out of Application Code

One purpose of AgentResult is to provide a common application-facing result abstraction. Instead of depending directly on provider SDK response objects:

Application
    |
    +---- OpenAI response
    |
    +---- Anthropic response
    |
    +---- Google response

application code can work through BindAI:

Application
    |
    v
Agent
    |
    v
Provider
    |
    v
AgentResult

This keeps provider-specific response types behind the provider abstraction. Provider and model capabilities can still affect execution behavior and available features.

Debugging Results

When debugging an agent execution, inspect the result type and values:

result = agent.run("Explain dependency injection.")

print(type(result))
print(result)
print(result.success)
print(result.output)
print(result.error)

For structured output, inspect the output type as well:

print(type(result.output))

This is useful when an application supports multiple output types or when structured conversion behavior needs to be verified.

Result Handling Best Practices

Use result.output to access completed agent output.
Check result.success when application behavior depends on successful execution.
Inspect result.error when a failed result is returned.
Handle Python exceptions separately.
Use structured output when downstream code requires predictable Python objects.
Do not assume structured conversion always succeeds.
Treat tool results separately from the final AgentResult.
Treat workflow results according to the workflow API.
Use streaming when incremental output is required.
Use run() when the application needs a completed result.
Keep provider-specific response handling out of application code.
Verify result types when supporting multiple BindAI versions or output types.
Test result handling against the BindAI version used by the application.

Summary

AgentResult is the primary result abstraction for completed BindAI agent execution. Its public fields are:

success
output
error

For normal text generation, the generated response is available through:

result.output

For structured execution, output can contain the constructed output object when JSON parsing and output-type construction succeed. If structured conversion fails in the current execution path, BindAI falls back to the raw response. A failed AgentResult can expose an error through:

result.error

but applications should also handle Python exceptions because not every execution failure necessarily becomes a failed AgentResult. Streaming is a separate execution mode and returns incremental provider output rather than a completed AgentResult. By using AgentResult instead of provider-specific response objects, applications can keep result handling consistent across supported model providers.

Getting Started

Core

Tools

Memory

Knowledge

Workflows

Projects

Templates

Connections

API Reference

Automation

Roadmap

02.5 results

Results

AgentResult

Accessing the Output

Checking Execution Status

Structured Output

Structured Output Processing

Structured Output Fallback

Inspecting Result Information

Handling Execution Failures

Results and Exceptions

Tool Results

Tool Execution Failures

Maximum Tool Iterations

Workflow Results

Result Flow

Results and Structured Applications

Results from Streaming

Result Handling in Applications

Keeping Provider Responses Out of Application Code

Debugging Results

Result Handling Best Practices

Summary

​Results

​AgentResult

​Accessing the Output

​Checking Execution Status

​Structured Output

​Structured Output Processing

​Structured Output Fallback

​Inspecting Result Information

​Handling Execution Failures

​Results and Exceptions

​Tool Results

​Tool Execution Failures

​Maximum Tool Iterations

​Workflow Results

​Result Flow

​Results and Structured Applications

​Results from Streaming

​Result Handling in Applications

​Keeping Provider Responses Out of Application Code

​Debugging Results

​Result Handling Best Practices

​Summary

Results

AgentResult

Accessing the Output

Checking Execution Status

Structured Output

Structured Output Processing

Structured Output Fallback

Inspecting Result Information

Handling Execution Failures

Results and Exceptions

Tool Results

Tool Execution Failures

Maximum Tool Iterations

Workflow Results

Result Flow

Results and Structured Applications

Results from Streaming

Result Handling in Applications

Keeping Provider Responses Out of Application Code

Debugging Results

Result Handling Best Practices

Summary