Agents

Creating and configuring Agents

Build powerful agentic workflows that can reason, use tools, and accomplish complex tasks autonomously.

Why use Agents?

Agents go beyond simple prompt-and-response. They can break down complex tasks, decide which tools to use, and iterate on their work without you having to script every step. This makes them a good fit for research, customer support, data processing, and other workflows where the path to the answer is not predictable.

Create an Agent

  1. Click Agents in the sidebar under Products.
  2. Click New Agent.
  3. Choose a starting point.
  4. Enter an Agent name and description, then select a model. Claude or GPT models usually work well for Agents.
  5. Click Create to open the Agent editor.

Starting from a template is the fastest way to get going. You can customize everything later. If you want to start from scratch, choose AI Assistant and clear the default content. You can also create an Agent from a Product by clicking Add Capability and then New Agent. This creates the Agent and adds it as a Capability in one step.

Configure your Agent

The Agent editor has a sidebar with configuration sections and a main editing area. The sidebar contains About, Model, Safety, Loop, and Error handling sections.

About

Use About to manage the basics: name, description, and icon. Agents themselves do not have a draft, active, paused, or archived lifecycle field; availability is controlled through product versions, Surface status, and which Capabilities are connected to each Surface.

Model

Select the model your Agent uses for reasoning.

You can also choose the Agent’s execution mode:

  • Use Model lets the Agent reason and respond with the selected model. This is the best choice for most use cases.
  • Use Flow lets the Agent run a primary Flow as its brain. Use this when you want tighter control over step-by-step logic.

Behavior

System prompt

The system prompt tells your Agent who it is and how to behave. Focus on goals, constraints, and priorities. The Agent can decide the exact steps.

Example

You are a customer research Agent. Your goal is to gather comprehensive information about customer requests by searching knowledge bases, looking up order history, and analyzing previous interactions. Always be thorough but concise. Prioritize recent information over historical data.

You can also start from a built-in system prompt template such as Helpful Assistant, Customer Support, or Technical Expert.

Temperature

Temperature controls how creative or focused the Agent’s responses are on a scale from 0 to 2. The default value of 0.7 works well for most Agents. Lower values produce more consistent outputs. Higher values allow more variation.

Claude 5 models (for example claude-sonnet-5) and GPT-5 family models (for example gpt-5, gpt-5-mini) do not support Temperature. The setting is ignored for Agents that use them.

Safety

The Safety section in the sidebar controls tool approval and tool call limits.

Tool Approval requires human approval before the Agent runs a tool call. Use this for higher-stakes workflows where you want a person to review actions before they happen. When an approval request appears, the Agent may include a short justification for the action, shown as Agent’s stated reason. This is the Agent’s own explanation of why it wants to run the tool — treat it as helpful context, not a system guarantee, and always review the tool name and parameters themselves before approving.

When Tool Approval is on, choose its scope: All tools gates every tool call, while Only selected lets you pick specific attached tools and capabilities from a list. In Only selected mode you can also add a custom pattern. A wildcard like mcp:* or builtin:* gates every tool of that type. The same patterns work per dispatch and in code: see dispatch-time approval overrides and Manage agents as code.

Approval rules match by tool name, so renaming a tool clears its rule. An empty selection in Only selected saves with Tool Approval turned off, so pick at least one tool before saving.

When Tool Approval is on, you can also turn on Allow ‘always allow’. This adds an Always allow option to the approval prompt, so the prompt then offers Always allow, Allow once, and Deny. When a user picks Always allow, Runtype remembers that decision and skips the prompt for that tool on future runs. Remembering an approval skips only the prompt, not authorization. Tool access, ownership, and secrets are unchanged. The setting is off by default.

Remembered approvals appear in the Remembered approvals card below the toggle. Each entry shows the tool and who it applies to (a specific user, or All users for an account-wide grant). Revoke any entry to restore the approval prompt for that tool on the next run.

Max Tool Calls sets how many tool calls the Agent can make in a single turn, from 1 to 100. This helps prevent excessive tool usage.

Agent Loop

Enable Agent Loop in the sidebar to let your Agent reason across multiple turns by thinking, acting, observing results, and deciding what to do next.

When Agent Loop is enabled, you can configure these settings:

  • Max Turns from 1 to 100 sets the maximum number of reasoning iterations. The Agent stops when it completes the task or reaches this limit.
  • Reflection enables periodic self-assessment at a configurable interval to help longer-running Agents stay on track.
  • Cost Budget sets a maximum spend in USD for a single execution. The Agent stops if it reaches that limit.

Start with 5 to 10 max turns and adjust after testing. Many tasks finish in only a few iterations.

Error handling

The Error handling section in the sidebar controls what happens when your Agent’s model fails or returns nothing. It opens a modal with three modes:

  • Continue on error lets the Agent keep going past the failure.
  • Stop on error halts the Agent immediately.
  • Use fallbacks tries a chain of alternatives before giving up.

A fallback chain runs each fallback in order until one succeeds. Each fallback is one of three types:

  • Retry re-runs the same model.
  • Different model switches to a backup model, with an optional temperature and max tokens override.
  • Fixed message returns a pre-written reply without calling a model. Use this as the last fallback so the Agent always produces a reply.

You also choose what triggers the chain. The step errors runs fallbacks when the model fails outright. The reply is empty runs them when the model finishes successfully but returns no visible text. You can enable both triggers at once.

Temporal awareness

Models have no built-in sense of time. An Agent’s temporal configuration adds two opt-in capabilities — a default timezone for the temporal tools and an automatic elapsed-time notice between messages.

  • timezone — the Agent’s default IANA timezone (for example, America/New_York). The temporal tools use it when no explicit timezone is passed to a tool and the conversation has no stored timezone of its own.
  • injectElapsed — when enabled, the Agent receives a short “time has passed” notice at the start of a turn whenever a user replies after a gap. This keeps the Agent from treating a message sent hours later as if it immediately followed the previous one. It applies only inside a conversation, from the second message onward.
  • elapsedThresholdSeconds — the minimum gap, in seconds, before the notice is added. It defaults to 30, so quick back-and-forth replies are not annotated. Raise it (for example, to 300) if you only care about gaps of several minutes or more.
  • groundNow — when enabled, the notice also includes the current date and time in the resolved timezone, giving the Agent an explicit “now” anchor.

The elapsed-time notice renders in the user’s local zone when one has been stored for the conversation, then the Agent’s default timezone, then UTC.

Memory

An Agent’s memory configuration gives it long-term memory that persists across conversations. When enabled, Runtype auto-injects three memory tools (save_memory, recall_memory, memory_summary) and ingests each user and assistant exchange in the background, so the Agent can recall facts a user shared days or weeks earlier.

  • enabled — set to true to turn on memory for this Agent. The three memory tools become available automatically; you do not add them to the tools list yourself.
  • profileTemplate — optional. Controls which memory bucket each execution reads from and writes to. If omitted, a saved Agent uses its own ID ({{_agent.id}}) — one shared bucket per Agent, the right default for personal and single-tenant deployments. To shard memory per Runtype account, set {{_user.id}}; to shard per Product Tenant (a company or workspace in a multi-tenant SaaS, shared by all of its users), set {{_tenant.id}}; to shard per individual SaaS end-user, set {{_endUser.id}}.
  • injectSummary — optional, defaults to true when memory is enabled. Runtype fetches a summary of what the Agent already knows and weaves it into the system prompt on each turn, so the Agent always has the user in context without having to call recall_memory first. Set to false to opt out — useful for focused task Agents that do not benefit from a profile overview.

By default (with injectSummary on), an Agent that you greet with “what should we work on today?” already has your standing preferences, recent decisions, and active tasks in context — it does not need a prompt to go look them up. The injected summary covers the whole profile, and is cached per profile so the cost of generating it is paid once rather than on every turn.

If a profileTemplate references a variable that cannot be resolved at runtime (for example {{_endUser.id}} when no end-user is provided), memory is disabled for that execution and a warning is logged — it never falls back to a shared bucket, so one user’s memories are never exposed to another.

You can also enable or override memory per call by including memory in the agentInput of a /v1/dispatch request, which is useful when the end-user identity is only known at dispatch time. The per-call memory object accepts the same fields as the saved configuration — enabled, profileTemplate, and injectSummary — so you can also control summary injection per dispatch. Inline dispatch agents (those with no saved Agent ID) must set an explicit profileTemplate — without a stable Agent identity there is no safe per-Agent default, so memory stays off until you scope a bucket.

Memory applies to standard Runtype Agents. Claude-managed Agents use Claude’s own native memory, so the memory configuration has no effect on them.

Tools

The tools area is where you give your Agent access to tools and sub-Agents.

Adding tools

  1. Click the tools area in the Agent editor.
  2. Click Add Tool or Configure Tools.
  3. Select the tools you want to add.
  4. Click Apply Changes.

The Agent decides which tools to call based on the task. You do not need to script the order.

Writing good tool descriptions

Tool descriptions help the Agent understand when to use a tool, why to use it, and what result to expect. Clear descriptions improve tool selection.

Good

Searches the knowledge base for articles matching a query. Use this to find documentation, FAQs, or policy information. Returns the top 5 matching articles with titles and snippets.

Too vague

Searches stuff.

Write tool descriptions the way you would explain the tool to a new teammate. Say what it does, when to use it, and what it returns.

Sub-Agents

You can also add other Flows or Agents as tools. This helps you build more advanced workflows, such as a research Agent that delegates parts of the job to specialized sub-Agents.

Test your Agent

  1. In the Agent editor, click Test Agent.
  2. Enter a test message or goal.
  3. Send the message and review how the Agent responds.

The test panel shows the decisions the Agent makes, the tools it calls, and the results it receives. This makes it easier to tune prompts, tools, and loop settings.

Test with a range of realistic inputs, including edge cases. This helps you refine the system prompt, tool selection, and loop settings.

Add your Agent to a Product

Once your Agent is configured and tested, add it to a Product so it can be used through that Product’s Surfaces.

  1. Open your Product.
  2. Click Add Capability.
  3. Select your Agent.
  4. Click Add Capability.

If you want more detail on how Capabilities work inside a Product, see Adding Capabilities to a product.

Your Agent is then available through any Surface connected to that Product, such as chat, API, or MCP.

Best practices

  • Start with a template. Use a built-in template to move faster, then tailor it to your use case.
  • Keep tools focused. Start with two or three tools and add more only when needed. Fewer, well-described tools usually produce better decisions.
  • Write clear instructions. A strong system prompt with clear goals and constraints improves Agent quality.
  • Test iteratively. Try varied inputs and refine the Agent based on how it reasons.
  • Use Agent Loop thoughtfully. Turn it on when the task benefits from multi-step reasoning, then set sensible limits.
  • Use cost budgets. Cost budgets help you control spend for each execution.

Next steps