Agents

An Agent wraps an LLM in a loop: it sends the conversation and its tools to the model, runs the tools the model asks for, sends the results back, and repeats until the model answers without calling a tool. The same object keeps its history between runs, so it carries a conversation.

from gwenflow import Agent, ChatOpenAI
from gwenflow.tools import WikipediaTool

agent = Agent(
    name="Research Assistant",
    description="Answers general-knowledge questions from Wikipedia.",
    instructions=[
        "Answer concisely, using your tools when needed.",
        "Cite the Wikipedia page you used.",
    ],
    llm=ChatOpenAI(model="gpt-5-mini"),
    tools=[WikipediaTool()],
)

response = agent.run("Summarize the Wikipedia page about Winston Churchill.")
print(response.content)

Configuration

Parameter	Meaning
`name`	the agent’s name: used in traces, as the tool name of a team member, and in activity names when durable
`description`	what the agent does: how a manager agent decides to delegate to it
`instructions`	a string or a list of strings, rendered in the system prompt
`system_prompt`	a complete system prompt that replaces the generated one (instructions, skills and memory are then not rendered)
`llm`	the model; defaults to `ChatOpenAI()`. The agent works on its own copy.
`tools`	the tools the model may call
`mcp_servers`	MCP servers whose tools are added to the agent’s
`tool_choice`	`"auto"`, `"required"`, `"none"` or a tool name
`response_model`	a Pydantic model or a JSON schema for a structured answer
`max_turns`	the cap on model calls in one run (default 100)
`history`	a custom memory buffer; by default one is built on 85 % of the model’s window
`summarizer`	a cheaper model for summarizing the history when it is compacted
`retriever`	a retriever queried with the task before each run
`skills`	skills the agent may load
`memory`	a long-term memory toolset
`team`, `subagents`	delegation to other agents
`reasoning_model`	a model that works through the task before the main one. See Reasoning.
`durability`	a durable execution backend, `TemporalDurability()`

Context-management options (max_tool_output_tokens, warn_near_limits, on_context_usage) are described in Context management.

The system prompt

Unless you give a complete system_prompt, the agent builds one for every request from, in this order:

## Instructions: each entry of instructions as a bullet;
## Skills: the name and description of each skill;
the JSON schema of the response_model;
## Memory: the long-term memory block;
<references>: the passages the retriever found for the task;
<context>: the context passed to the run.

The stable parts come first and the per-run parts last, so the prefix the provider caches stays identical from one request to the next. agent.get_system_prompt(task, context) returns what the model would receive. Instructions that take parameters can be rendered with PromptTemplate (gwenflow.prompts), a thin wrapper over str.format that can read a template from a file:

from gwenflow.prompts import PromptTemplate

template = PromptTemplate.from_file("prompts/support.md")   # "You support {product} customers in {language}."
agent = Agent(name="Support", llm=llm, instructions=template.format(product="Atlas", language="French"))

Running

response = agent.run("What's the capital of Peru?")
response = await agent.arun("What's the capital of Peru?")

The input is a string, a list of messages or a list of OpenAI-style dicts. run_stream and arun_stream yield events as the run progresses; see Streaming.

Passing context

context adds information to the system prompt for this run only, without storing it in the history:

agent.run(
    "Write a reply to the customer.",
    context={
        "customer": "Jane Doe, premium plan since 2021",
        "ticket": "The export to CSV fails with a timeout.",
    },
)

A string is wrapped in a <context> block; a dict gives one block per key.

Conversations

The history persists on the agent, so successive runs form a conversation:

agent.run("My name is Ada.")
print(agent.run("What's my name?").content)   # Ada

agent.history.reset()                          # start over

To serve several users, give each conversation its own agent: agent.clone() returns a copy with the same configuration and an empty history. To restore a saved conversation, add its messages to the history before running:

saved = [m.to_dict() for m in agent.history.messages]
...
agent = template.clone()
agent.history.add_messages(saved)

The response

run returns an AgentResponse: content, parsed, finish_reason (stop, max_turns, approval_required), messages, events, usage and delegation_usage. See Messages and responses.

Limits

max_turns caps the number of model calls in a run. When it is reached, the run ends with finish_reason="max_turns" and no answer:

agent = Agent(name="Researcher", llm=llm, tools=tools, max_turns=20)
response = agent.run("...")
if response.finish_reason == "max_turns":
    ...

With warn_near_limits=True the model is told, in the system prompt of the request, when it is close to the limit, so it concludes instead of being cut off. See Context management.

Usage

response.usage sums the tokens, requests and tool calls of the run, including the summaries of a compaction and the runs of delegated agents. agent.total_usage sums every run of the agent:

u = agent.total_usage
print(f"{u.requests} requests, {u.input_tokens} in, {u.output_tokens} out, {u.tool_calls} tool calls")

AgentUsage also counts cache_read_tokens and cache_write_tokens for providers that report prompt caching. The library does not price tokens itself; Agent(pricing={"input": 3.0, "output": 15.0}) (dollars per million tokens, with optional cache_read and cache_write) is a place to keep your grid for callers that estimate costs from total_usage.

Tools on the agent

Besides tools=[...], a function becomes a tool of one agent with the @agent.tool decorator:

@agent.tool
def get_stock_price(ticker: str) -> str:
    """Get the latest stock price for a ticker symbol."""
    ...

@agent.tool(requires_approval=True)
def place_order(ticker: str, quantity: int) -> str:
    """Place a buy order."""
    ...

See Tools and Tool approvals.

Retrieval

With a retriever, the agent searches it with the task before calling the model and adds the best passages to the system prompt as references:

from gwenflow import Agent, Retriever

retriever = Retriever(name="handbook")
retriever.load_documents(documents)

agent = Agent(name="HR assistant", llm=llm, retriever=retriever)

See Retrieval (RAG).

Get started

Concepts

Models

Multi-agent

Extend

Memory

Flows

Knowledge

Production

Project

Agents

Configuration

The system prompt

Running

Passing context

Conversations

The response

Limits

Usage

Tools on the agent

Retrieval

​Configuration

​The system prompt

​Running

​Passing context

​Conversations

​The response

​Limits

​Usage

​Tools on the agent

​Retrieval

Configuration

The system prompt

Running

Passing context

Conversations

The response

Limits

Usage

Tools on the agent

Retrieval