agent-builder

Build a Railtracks Agent

The user wants to build an agent using the railtracks framework: $ARGUMENTS

How railtracks works

• Tools are plain Python functions decorated with @rt.function_node. Type hints become the parameter schema; the docstring becomes the description.
• Agents are created with rt.agent_node(). Its behaviour depends on whether tools or a structured output schema are passed (see below).
• Flows wrap an agent or async function as the entry point and handle execution, config, and context.
• rt.call() is used inside async workflows to call agents or nodes directly.
• Results: flow.invoke(), await flow.ainvoke() and await rt.call() on an agent return a response object. Read it with .content: a str for a text agent, an instance of your schema for an output_schema agent. The full conversation is on .message_history. When the agent was given an output_schema, .structured also returns that instance; otherwise .text also returns the str.

What agent_node builds

rt.agent_node() builds one node behind the scenes — there is no separate named type to pick. What you pass changes what the agent does at runtime:

Passed	Behaviour
Neither tool_nodes nor output_schema	Plain chat, text output
output_schema only	Structured output, no tools
tool_nodes only	Tool-calling loop, text output

LLM Providers

# Example model IDs; use the provider and model the project already uses
rt.llm.AnthropicLLM("claude-sonnet-5-5")
rt.llm.OpenAILLM("gpt-6-luna")
rt.llm.GeminiLLM("gemini-3.8-flash")
rt.llm.OpenAICompatibleProvider(
    "my-model", api_base="https://api.example.com/v1", api_key="..."
)

---

Steps

1. Read the existing code — check what files already exist in the project. Understand the task before writing anything.
2. Identify what tools the agent needs — each capability the agent should have becomes a @rt.function_node. Ask the user to clarify if it's not obvious from $ARGUMENTS.
3. Define the tools — write each tool as a Python function with:
   • Full type hints on all parameters and return value
   • A docstring with a one-line summary and Args: / Returns: sections
   • Real implementation (or a clear stub with a TODO if the user needs to fill it in)
4. Define the agent — call rt.agent_node() with (note: it returns a class/type, so use PascalCase for the variable name):
   • A descriptive name
   • tool_nodes listing the tools (if any), or output_schema as a Pydantic BaseModel for structured output — one or the other, never both (passing both raises NodeCreationError)
   • llm — follow the provider the project already uses, or one whose API key is configured (providers and their key variables: https://docs.railtracks.org/documentation/getting_started/llm_setup/); otherwise ask the user which LLM to use
   • system_message — a clear, specific system prompt
5. Wrap in a Flow — create rt.Flow(name="...", entry_point=MyAgent) for simple cases. For multi-step or multi-agent workflows, define an async def function as the entry point and use await rt.call(MyAgent, ...) inside it.
6. Add invocation code — include a if __name__ == "__main__": block that calls flow.invoke(...) with a representative example and prints result.content, so the user can run it immediately. Use await flow.ainvoke(...) instead if the code is already async.
7. Check imports — make sure import railtracks as rt is at the top and any Pydantic models import from pydantic import BaseModel.