agent.agent_result

Data structures for agentic execution results.

class ToolCallRecord(round, tool_name, tool_call_id='', arguments=<factory>, result='', duration_ms=0.0, error=None)[source]

Bases: object

Record of a single tool call within an agentic loop.

Parameters:

round (int)
tool_name (str)
tool_call_id (str)
arguments (dict[str, Any])
result (str)
duration_ms (float)
error (str | None)

round

The round number (1-indexed) when this call was made.

Type:: int

tool_name

Name of the tool that was called.

Type:: str

tool_call_id

Provider-specific ID for the tool call.

Type:: str

arguments

Arguments passed to the tool.

Type:: dict[str, Any]

result

The tool’s return value as a string.

Type:: str

duration_ms

Wall-clock duration of tool execution in milliseconds.

Type:: float

error

Error message if the tool execution failed, None otherwise.

Type:: str | None

round: int

tool_name: str

tool_call_id: str = ''

arguments: dict[str, Any]

result: str = ''

duration_ms: float = 0.0

error: str | None = None

to_dict()[source]

Convert to dictionary for serialization.

Return type:: dict[str, Any]

classmethod from_dict(data)[source]

Create from dictionary.

Parameters:: data (dict[str, Any])
Return type:: ToolCallRecord

class AgentResult(response='', tool_calls=<factory>, total_rounds=0, total_llm_calls=0, status='success')[source]

Bases: object

Result of an agentic execution loop.

Parameters:

response (str)
tool_calls (list[ToolCallRecord])
total_rounds (int)
total_llm_calls (int)
status (Literal['success', 'failed', 'max_rounds_exceeded'])

response

The final response text from the LLM.

Type:: str

tool_calls

List of tool call records from all rounds.

Type:: list[ffai.agent.agent_result.ToolCallRecord]

total_rounds

Number of rounds executed.

Type:: int

total_llm_calls

Total number of LLM API calls made.

Type:: int

status

Execution status - “success”, “failed”, or “max_rounds_exceeded”.

Type:: Literal[‘success’, ‘failed’, ‘max_rounds_exceeded’]

response: str = ''

tool_calls: list[ToolCallRecord]

total_rounds: int = 0

total_llm_calls: int = 0

status: Literal['success', 'failed', 'max_rounds_exceeded'] = 'success'

property tool_calls_count: int: Total number of tool calls made.

property last_tool_name: str: Name of the last tool called, or empty string if no tools used.

property failed_tool_calls: list[ToolCallRecord]: List of tool calls that resulted in errors.

to_dict()[source]

Convert to dictionary for serialization.

Return type:: dict[str, Any]

classmethod from_dict(data)[source]

Create from dictionary.

Parameters:: data (dict[str, Any])
Return type:: AgentResult

Classes

class AgentResult(response='', tool_calls=<factory>, total_rounds=0, total_llm_calls=0, status='success')[source]

Bases: object

Result of an agentic execution loop.

Parameters:

response (str)
tool_calls (list[ToolCallRecord])
total_rounds (int)
total_llm_calls (int)
status (Literal['success', 'failed', 'max_rounds_exceeded'])

response

The final response text from the LLM.

Type:: str

tool_calls

List of tool call records from all rounds.

Type:: list[ffai.agent.agent_result.ToolCallRecord]

total_rounds

Number of rounds executed.

Type:: int

total_llm_calls

Total number of LLM API calls made.

Type:: int

status

Execution status - “success”, “failed”, or “max_rounds_exceeded”.

Type:: Literal[‘success’, ‘failed’, ‘max_rounds_exceeded’]

response: str = ''

tool_calls: list[ToolCallRecord]

total_rounds: int = 0

total_llm_calls: int = 0

status: Literal['success', 'failed', 'max_rounds_exceeded'] = 'success'

property tool_calls_count: int: Total number of tool calls made.

property last_tool_name: str: Name of the last tool called, or empty string if no tools used.

property failed_tool_calls: list[ToolCallRecord]: List of tool calls that resulted in errors.

to_dict()[source]

Convert to dictionary for serialization.

Return type:: dict[str, Any]

classmethod from_dict(data)[source]

Create from dictionary.

Parameters:: data (dict[str, Any])
Return type:: AgentResult

class ToolCallRecord(round, tool_name, tool_call_id='', arguments=<factory>, result='', duration_ms=0.0, error=None)[source]

Bases: object

Record of a single tool call within an agentic loop.

Parameters:

round (int)
tool_name (str)
tool_call_id (str)
arguments (dict[str, Any])
result (str)
duration_ms (float)
error (str | None)

round

The round number (1-indexed) when this call was made.

Type:: int

tool_name

Name of the tool that was called.

Type:: str

tool_call_id

Provider-specific ID for the tool call.

Type:: str

arguments

Arguments passed to the tool.

Type:: dict[str, Any]

result

The tool’s return value as a string.

Type:: str

duration_ms

Wall-clock duration of tool execution in milliseconds.

Type:: float

error

Error message if the tool execution failed, None otherwise.

Type:: str | None

round: int

tool_name: str

tool_call_id: str = ''

arguments: dict[str, Any]

result: str = ''

duration_ms: float = 0.0

error: str | None = None

to_dict()[source]

Convert to dictionary for serialization.

Return type:: dict[str, Any]

classmethod from_dict(data)[source]

Create from dictionary.

Parameters:: data (dict[str, Any])
Return type:: ToolCallRecord