Messages and responses

Gwenflow speaks one format to every provider. You build Message objects (or plain strings and dicts), and each client translates them to its own wire format; what comes back is a ModelResponse from an LLM and an AgentResponse from an agent. All of them live in gwenflow.types.

Input

Models and agents accept three shapes of input:

llm.invoke("Hello")                                        # a string: one user message

llm.invoke([                                               # OpenAI-style dicts
    {"role": "system", "content": "Answer in French."},
    {"role": "user", "content": "Hello"},
])

from gwenflow.types import Message
llm.invoke([Message(role="user", content="Hello")])        # Message objects

`Message`

Field	Meaning
`role`	`system`, `user`, `assistant` or `tool`
`content`	a string, or a list of content parts for multi-modal input
`tool_calls`	on an assistant message, the tool calls the model made
`tool_call_id`	on a tool message, the call it answers
`thinking_parts`	the reasoning to send back on the next turn, where the provider requires it (Anthropic extended thinking)
`name`, `extra`	optional name and provider-specific metadata

message.to_dict() and Message.from_dict() round-trip a message, which is how a conversation is saved and restored.

Content parts

A content list mixes parts of several kinds:

Part	Holds
`TextContent(content=...)`	text
`ImageContent`	an image, from a URL, a path or bytes
`AudioContent`	an audio clip
`FileContent`	a file, typically a PDF, from a path, bytes, a URL or a provider file id

See Multi-modal input.

`ModelResponse`: one model call

llm.invoke() returns a ModelResponse. Its parts keep what the model produced in order (text, thinking, tool calls, audio, images); properties regroup them by kind:

Attribute	Meaning
`text` (alias `content`)	the text of the answer
`thinking`	the model’s reasoning, when it exposes it. See Reasoning.
`tool_calls`	the `ToolCall`s requested: `id`, `name`, `arguments`
`parsed`	the validated object when a `response_format` was set
`audio`, `images`	generated audio and images
`usage`	a `RequestUsage`: `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, audio tokens
`finish_reason`	the provider’s stop reason

`AgentResponse`: one agent run

agent.run() returns an AgentResponse:

Attribute	Meaning
`content`	the final answer
`parsed`	the validated object when the agent has a `response_model`
`reasoning_content`	the reasoning accumulated over the run
`messages`	the assistant and tool messages produced during the run
`events`	the full event log of the run, the same events a stream yields
`pending_approvals`	the tool calls waiting for a human decision. See Tool approvals.
`finish_reason`	`stop`, `max_turns`, `approval_required`, or `interrupted` for a stream closed early
`usage`	an `AgentUsage`: the token counts plus `requests` and `tool_calls`, summed over the run
`delegation_usage`	the share of `usage` spent by team members and sub-agents
`run_id`, `agent_id`	identifiers of the run and the agent

response = agent.run("What's the exchange rate of the Euro?")

if response.finish_reason == "max_turns":
    print("The agent ran out of turns.")
print(response.content)
print(response.usage.input_tokens, response.usage.output_tokens, response.usage.tool_calls)

agent.total_usage adds up the usage of every run of the agent, including delegations.

Events

The events of a run share agent_id, run_id, event_type, content and metadata:

`event_type`	Class	When
`started`, `completed`	`AgentEventStarted`, `AgentEventCompleted`	the run starts and ends
`content`	`AgentEventContent`	a piece of the answer
`thinking`	`AgentEventThinking`	a piece of reasoning
`tool_started`, `tool_completed`	`AgentEventToolStarted`, `AgentEventToolCompleted`	a tool call starts (`tool_name`, `tool_args`, `tool_call_id`) and returns (`tool_call_id`, the result in `content`)
`tool_approval_required`	`AgentEventToolApprovalRequired`	a tool call waits for a decision
`subagent_started`, `subagent_completed`	`AgentEventSubagentStarted`, `AgentEventSubagentCompleted`	a sub-agent starts and finishes
`error`, `cancelled`	`AgentEventError`, `AgentEventCancelled`	the run failed or was cancelled

See Streaming for consuming them live.

Get started

Concepts

Models

Agents

Multi-agent

Extend

Memory

Flows

Knowledge

Production

Project

Messages and responses

Input

`Message`

Content parts

`ModelResponse`: one model call

`AgentResponse`: one agent run

Events

​Input

​Message

​Content parts

​ModelResponse: one model call

​AgentResponse: one agent run

​Events

Input

`Message`

Content parts

`ModelResponse`: one model call

`AgentResponse`: one agent run

Events