Sagents.AgentResult (Sagents v0.8.0-rc.8)

Copy Markdown

Helpers for reading structured results out of an Sagents.Agent.execute/3 return value.

Agent.execute/3 can return any of:

  • {:ok, %State{}} — normal completion. Last message may be assistant prose or an assistant tool call followed by tool results.
  • {:ok, %State{}, %ToolResult{}} — until_tool completion. The third element is the LangChain.Message.ToolResult produced by the target tool.
  • {:interrupt, %State{}, interrupt_data} — paused for HITL/ask-user.
  • {:pause, %State{}} — infrastructure pause.
  • {:error, term()} — execution failed.

This module's job is to translate those shapes into a focused payload for callers doing structured-extraction or single-invocation workflows. It is intentionally a thin read layer — it does not validate, retry, or coerce. It mirrors LangChain.Utils.ChainResult, which serves the same role for LLMChain.

Functions

  • tool_result/1 — pull the %ToolResult{} out of a 3-tuple, or find the last tool result in state.messages for the 2-tuple case.
  • tool_arguments/1 — the LLM-supplied arguments map. This is what structured-extraction callers want 95% of the time.
  • processed_content/1 — the native-Elixir payload, when the tool's body returned {:ok, "string", native_term}.
  • to_string/1 — extract a final assistant text response (for executions that ended in prose rather than a tool call). Mirrors LangChain.Utils.ChainResult.to_string/1.

All functions accept either an execute/3 return value or a bare %State{}. Error tuples pass straight through unchanged so callers can pipe.

Examples

iex> {:ok, _state, _tool_result} = result =
...>   Sagents.Agent.execute(agent, state, until_tool: "submit")
iex> {:ok, args} = Sagents.AgentResult.tool_arguments(result)

iex> {:ok, state} = Sagents.Agent.execute(agent, state)
iex> {:ok, text} = Sagents.AgentResult.to_string({:ok, state})

Summary

Types

execute_return()

Anything Agent.execute/3 can return, or a bare State.

Functions

processed_content(input)

Return the processed_content of the result tool — the native Elixir term a tool body can attach by returning {:ok, "string for LLM", native_term}.

to_string(passthrough)

Return the final assistant message content as a string.

tool_arguments(passthrough)

Return the LLM-supplied arguments map from the result tool call.

tool_result(passthrough)

Return the %ToolResult{} carried by an until_tool 3-tuple.

Types

execute_return()

@type execute_return() ::
  Sagents.State.t()
  | {:ok, Sagents.State.t()}
  | {:ok, Sagents.State.t(), LangChain.Message.ToolResult.t()}
  | {:interrupt, Sagents.State.t(), any()}
  | {:pause, Sagents.State.t()}
  | {:error, any()}

Anything Agent.execute/3 can return, or a bare State.

Functions

processed_content(input)

@spec processed_content(execute_return()) ::
  {:ok, any()} | {:error, LangChain.LangChainError.t()} | {:error, any()}

Return the processed_content of the result tool — the native Elixir term a tool body can attach by returning {:ok, "string for LLM", native_term}.

Useful when the tool wants to hand back something richer than a JSON-parseable argument map (a struct, a tuple, etc.).

to_string(passthrough)

@spec to_string(execute_return()) ::
  {:ok, String.t()} | {:error, LangChain.LangChainError.t()} | {:error, any()}

Return the final assistant message content as a string.

Mirrors LangChain.Utils.ChainResult.to_string/1. For executions that ended with prose rather than a tool call.

Returns {:error, %LangChainError{}} if the last message is not a complete assistant message.

tool_arguments(passthrough)

@spec tool_arguments(execute_return()) ::
  {:ok, map()} | {:error, LangChain.LangChainError.t()} | {:error, any()}

Return the LLM-supplied arguments map from the result tool call.

Prefers tool_call.arguments from the assistant message that produced the tool result (this is what the LLM actually emitted, already parsed from JSON by LangChain). Falls back to the 3-tuple's %ToolResult{} when the matching tool call can't be located.

This is the right call for structured-extraction workflows where the schema is the tool's parameters_schema.

tool_result(passthrough)

@spec tool_result(execute_return()) ::
  {:ok, LangChain.Message.ToolResult.t()}
  | {:error, LangChain.LangChainError.t()}
  | {:error, any()}

Return the %ToolResult{} carried by an until_tool 3-tuple.

For a 2-tuple or bare %State{}, walks back through state.messages and returns the most recent successful (non-error) tool result, if any. Returns {:error, %LangChainError{}} when no usable tool result is present.