Agent

Individual agent configuration and execution

The Agent class represents an individual AI agent that can be executed.

AgentBuilder

The recommended way to create agents is with AgentBuilder:

from splinter.workflow import AgentBuilder
from splinter.types import LLMProvider

agent = (
    AgentBuilder("researcher")
    .with_provider(LLMProvider.OPENAI, "gpt-4o")
    .with_system_prompt("Research topics. Output JSON.")
    .with_tools(["web_search"])
    .with_state_ownership(["research.*"])
    .build(gateway)
)

AgentBuilder Methods

Method	Description
with_provider(provider, model)	Set LLM provider and model
with_system_prompt(prompt)	Set system prompt
with_tools(tools)	Set allowed tools
with_state_ownership(patterns)	Set state ownership patterns
with_config(config)	Set full AgentConfig
build(gateway)	Build the agent

Agent Methods

run()

Execute the agent.

async def run(
    task: str,
    context: dict[str, Any] | None = None,
) -> dict[str, Any]

Parameter	Type	Description
task	str	What the agent should do
context	dict | None	Additional context

result = await agent.run(task="Research AI trends")
result = await agent.run(
    task="Analyze this data",
    context={"data": [1, 2, 3]}
)

AgentConfig

Configuration dataclass for agents:

from splinter.types import AgentConfig, LLMProvider

config = AgentConfig(
    agent_id="researcher",
    provider=LLMProvider.OPENAI,
    model="gpt-4o",
    system_prompt="Research topics. Output JSON.",
    tools=["web_search", "read_file"],
    state_ownership=["research.*"],
    max_steps=50,
    temperature=0.7,
)

AgentConfig Fields

Field	Type	Default	Description
agent_id	str	Required	Unique identifier
provider	LLMProvider	Required	LLM provider to use
model	str	Required	Model name
system_prompt	str	""	System prompt
tools	list[str]	[]	Allowed tools
state_ownership	list[str]	[]	State ownership patterns
max_steps	int | None	None	Max steps for this agent
temperature	float	0.7	Temperature

LLMProvider

Supported providers:

from splinter.types import LLMProvider

LLMProvider.OPENAI      # OpenAI (GPT-4, GPT-4o)
LLMProvider.ANTHROPIC   # Anthropic (Claude)
LLMProvider.GEMINI      # Google (Gemini)
LLMProvider.GROK        # xAI (Grok)

Full Example

from splinter.workflow import AgentBuilder
from splinter.gateway import Gateway
from splinter.types import ExecutionLimits, LLMProvider

# Create gateway with limits
gateway = Gateway(
    limits=ExecutionLimits(max_budget=10.0, max_steps=100)
)
gateway.configure_provider("openai", api_key="sk-...")

# Build agent
agent = (
    AgentBuilder("researcher")
    .with_provider(LLMProvider.OPENAI, "gpt-4o")
    .with_system_prompt("""
        You are a research assistant.
        Research the given topic thoroughly.
        Output your findings as JSON: {"findings": [...], "sources": [...]}
    """)
    .with_tools(["web_search"])
    .build(gateway)
)

# Run agent
result = await agent.run(task="Research AI trends for 2024")
print(result)
# {"findings": [...], "sources": [...]}