Agent Components¶

An agent component defines an AI agent that can reason, use tools, follow instructions, and produce structured output. Agents are the primary way to add intelligence to a solution.

Agent Definition¶

An agent component wires together the pieces an AI agent needs: a model for inference, tools for capabilities, prompts for instructions, schemas for structured output, and state for memory.

graph TD
    Agent["Agent Component"]
    Model["Model<br/>LLM configuration"]
    Tools["Tools<br/>Callable capabilities"]
    Prompt["Prompt<br/>System instructions"]
    Schema["Schema<br/>Output structure"]
    State["State<br/>Conversation memory"]
    Obs["Observability<br/>Tracing config"]

    Agent -->|"model_ref"| Model
    Agent -->|"tool_refs"| Tools
    Agent -->|"prompt_ref"| Prompt
    Agent -->|"schema_refs"| Schema
    Agent -->|"state_ref"| State
    Agent -->|"observability_ref"| Obs

Creating an Agent¶

PythonUI

Coming Soon

The Python SDK for local development is not yet publicly available.

from flow_sdk.cli_client import CLIClient

client = CLIClient(config)

agent = client.agents.create({
    "name": "Customer Support Agent",
    "slug": "customer-support-agent",
    "description": "Handles customer inquiries with access to knowledge base and ticketing",
    "framework": "pydantic_ai",
    "model_ref": "<model-component-uuid>",
    "tool_refs": [
        "<search-kb-tool-uuid>",
        "<create-ticket-tool-uuid>",
    ],
    "prompt_ref": "<support-prompt-uuid>",
    "schema_refs": {
        "output": "<ticket-response-schema-uuid>",
    },
    "enable_conversations": True,
    "tags": ["support", "production"],
})

Navigate to Components > Agents > New. Configure name, framework, model, tools, prompt, and schemas. Click Create.

Configuration¶

Required Fields¶

Field	Type	Description
`name`	string	Display name (max 200 chars)
`slug`	string	URL-safe identifier
`model_ref`	UUID	Reference to a Model component

Optional Fields¶

Field	Type	Default	Description
`framework`	enum	`pydantic_ai`	Agent framework: `pydantic_ai`, `langchain`, `google_adk`, `strands`
`tool_refs`	UUID[]	`[]`	References to Tool components
`prompt_ref`	UUID	`null`	Reference to a Prompt component
`state_ref`	UUID	`null`	Reference to a State component
`workflow_ref`	UUID	`null`	Reference to a Workflow component for structured execution
`schema_refs`	dict	`{}`	Map of schema roles to Schema component UUIDs (e.g., `{"output": "<uuid>"}`)
`observability_ref`	UUID	`null`	Reference to an Observability component
`enable_conversations`	bool	`false`	Enable multi-turn conversation persistence
`persona_constraints`	string[]	`[]`	Restrict which roles can execute this agent

System Prompts¶

The agent's behavior is primarily controlled by its prompt component. The prompt defines the system message, few-shot examples, and dynamic templates.

An agent can use prompts in two ways:

Static prompt ref -- A Prompt component referenced via prompt_ref. The prompt's system message and templates are injected at runtime.
Schema-driven output -- When schema_refs.output points to a Schema component, the agent is instructed to produce structured output matching that schema.

Coming Soon

The Python SDK for local development is not yet publicly available.

# Create a prompt with variable interpolation
prompt = client.prompts.create({
    "name": "Support Agent Instructions",
    "slug": "support-agent-instructions",
    "system_message": """You are a customer support agent for {{company_name}}.

Your responsibilities:
- Answer questions using the knowledge base
- Create support tickets for issues you cannot resolve
- Always be polite and professional

Current customer: {{customer_name}}
Account tier: {{account_tier}}""",
    "static_templates": [],
    "dynamic_function_refs": [],
})

# Reference it from the agent
agent = client.agents.create({
    "name": "Support Agent",
    "slug": "support-agent",
    "model_ref": model["id"],
    "prompt_ref": prompt["id"],
})

Tools¶

Tools give agents the ability to take actions and access external data. Each tool reference points to a Tool component that defines what the tool does, its parameters, and its implementation.

Coming Soon

The Python SDK for local development is not yet publicly available.

# Agent with multiple tools
agent = client.agents.create({
    "name": "Research Agent",
    "slug": "research-agent",
    "model_ref": model["id"],
    "tool_refs": [
        search_tool["id"],      # Search the knowledge base
        fetch_url_tool["id"],   # Fetch content from URLs
        summarize_tool["id"],   # Summarize long documents
    ],
})

Tool selection

Agents automatically select which tools to use based on the user's request and the tool descriptions. Write clear, specific tool descriptions to help the agent make good choices.

Model Selection¶

The model_ref field points to a Model component that configures which LLM to use, along with parameters like temperature, max tokens, and timeout.

Different agents in the same solution can use different models. For example, a classifier agent might use a fast, inexpensive model while a response-generation agent uses a more capable model:

Coming Soon

The Python SDK for local development is not yet publicly available.

# Fast model for classification
classifier_model = client.models.create({
    "name": "Fast Classifier",
    "slug": "fast-classifier",
    "model": "openai/gpt-4o-mini",
    "provider": "openai",
    "temperature": 0.0,
    "max_tokens": 100,
})

# Capable model for response generation
response_model = client.models.create({
    "name": "Response Writer",
    "slug": "response-writer",
    "model": "anthropic/claude-sonnet-4-20250514",
    "provider": "anthropic",
    "temperature": 0.7,
    "max_tokens": 2000,
})

Conversations¶

When enable_conversations is true, the agent maintains a conversation session across multiple interactions. Each execution within a session has access to all previous messages, allowing multi-turn dialogue.

Sessions are tracked through the ExecutionSession system:

from flow_sdk import FlowSDK

sdk = FlowSDK()

# Start a conversation
response1 = await sdk.agents.run(
    agent_id=agent["id"],
    input_data={"message": "I need help with my billing"},
)

session_id = response1["session_id"]

# Continue the conversation
response2 = await sdk.agents.run(
    agent_id=agent["id"],
    session_id=session_id,
    input_data={"message": "Can you show me my last 3 invoices?"},
)

Agent Testing¶

Test agents using the platform's execution system before deploying them to production.

Quick Test¶

Execute an agent directly against its current configuration (no deployment required):

from flow_sdk import FlowSDK

sdk = FlowSDK()

result = await sdk.agents.run(
    agent_id=agent["id"],
    input_data={"message": "What is your return policy?"},
)

print(f"Status: {result['status']}")
print(f"Output: {result['output_data']}")
print(f"Execution time: {result['execution_time_ms']}ms")

Checking Tool Usage¶

The execution response includes details about which tools the agent called:

from flow_sdk import FlowSDK

sdk = FlowSDK()

# Submit an async execution and poll for results
handle = await sdk.agents.submit(
    agent_id=agent["id"],
    input_data={"message": "Find articles about refund policies"},
)

status = await sdk.agents.get_status(handle["execution_id"])

print(f"Status: {status['status']}")
if status["status"] == "completed":
    for step in status["steps"]:
        if step["type"] == "tool_call":
            print(f"Tool: {step['name']}")
            print(f"Args: {step['arguments']}")
        elif step["type"] == "message":
            print(f"Agent: {step['content']}")

Structured Output¶

Use schema_refs.output to constrain agent responses to a specific structure. The platform auto-generates an output schema from workflow edge conditions, or you can create one manually:

Coming Soon

The Python SDK for local development is not yet publicly available.

# Define the output schema
output_schema = client.schemas.create({
    "name": "Ticket Classification Output",
    "slug": "ticket-classification-output",
    "schema_type": "json_schema",
    "fields": [
        {"name": "category", "type": "string", "required": True,
         "enum": ["billing", "technical", "general"]},
        {"name": "priority", "type": "string", "required": True,
         "enum": ["low", "medium", "high", "critical"]},
        {"name": "summary", "type": "string", "required": True},
    ],
})

# Attach to agent
agent = client.agents.update(agent["id"], {
    "schema_refs": {"output": output_schema["id"]},
})

Auto-generated schemas

When an agent is used as a workflow node with conditional edges, the platform can auto-generate an output schema by extracting field references from the edge conditions. See Workflows for details.