Custom Agents

Define reusable agent patterns

Agent Definition Pattern

Create reusable agent definitions like OpenAI Assistants.

from dataclasses import dataclass

@dataclass
class AgentDefinition:
    name: str
    instructions: str
    tools: list[str]
    model: str = "gpt-4o-mini"
    state_ownership: list[str] = None
    output_schema: dict = None

Example Agents

Research Agent

RESEARCH_AGENT = AgentDefinition(
    name="ResearchAgent",
    instructions="""You are a research specialist.

Output JSON:
{
    "findings": ["fact1", "fact2"],
    "sources": ["source1"],
    "confidence": 0.9
}""",
    tools=["web_search", "read_document"],
    state_ownership=["research.*"],
)

Analysis Agent

ANALYSIS_AGENT = AgentDefinition(
    name="AnalysisAgent",
    instructions="""You analyze research findings.

Output JSON:
{
    "summary": "...",
    "insights": ["insight1"],
    "significance": 8
}""",
    tools=["calculate", "visualize"],
    state_ownership=["analysis.*"],
)

Writer Agent

WRITER_AGENT = AgentDefinition(
    name="WriterAgent",
    instructions="""You create content.

Output JSON:
{
    "title": "...",
    "content": "...",
    "word_count": 500
}""",
    tools=["grammar_check"],
    state_ownership=["content.*"],
)

Factory Function

from splinter import AgentBuilder, LLMProvider

def create_agent(definition: AgentDefinition, gateway) -> Agent:
    builder = (
        AgentBuilder(definition.name.lower())
        .with_provider(LLMProvider.OPENAI, definition.model)
        .with_system_prompt(definition.instructions)
        .with_tools(definition.tools)
    )

    if definition.state_ownership:
        builder.with_state_ownership(definition.state_ownership)

    if definition.output_schema:
        builder.with_output_schema(definition.output_schema)

    return builder.build(gateway)

Usage

gateway = Gateway()
gateway.configure_provider("openai", api_key="sk-...")

researcher = create_agent(RESEARCH_AGENT, gateway)
analyst = create_agent(ANALYSIS_AGENT, gateway)
writer = create_agent(WRITER_AGENT, gateway)

# Use in workflow
workflow = Workflow(workflow_id="content-pipeline")
workflow._gateway = gateway

for agent in [researcher, analyst, writer]:
    workflow.add_agent(agent.config)

workflow.add_step("researchagent")
workflow.add_step("analysisagent", depends_on=["researchagent"])
workflow.add_step("writeragent", depends_on=["analysisagent"])

Team Patterns

Research Team

RESEARCH_TEAM = [
    AgentDefinition(name="Searcher", ...),
    AgentDefinition(name="Extractor", ...),
    AgentDefinition(name="Verifier", ...),
]

Content Team

CONTENT_TEAM = [
    AgentDefinition(name="Researcher", ...),
    AgentDefinition(name="Writer", ...),
    AgentDefinition(name="Editor", ...),
    AgentDefinition(name="Reviewer", ...),
]

Analysis Team

ANALYSIS_TEAM = [
    AgentDefinition(name="DataCollector", ...),
    AgentDefinition(name="Analyst", ...),
    AgentDefinition(name="Visualizer", ...),
    AgentDefinition(name="Reporter", ...),
]