Creating and configuring Agents

Use Agents to build workflows that select tools, run Flows, and continue across multiple turns.

Why use Agents?

Agents handle tasks whose next step depends on the incoming message or an earlier tool result. You provide a goal, instructions, a model, and tools. The model selects tool calls at run time instead of following a fixed sequence that you script.

Use Agents for research, customer support, data processing, and other workflows with variable paths.

Create an Agent

To create an Agent, follow these steps:

1. In the sidebar, click Agents under Products.
2. On the Agents page, click New Agent.
3. Select a starting point.
4. Enter a name in Name and a description in Description.
5. Select a model.
6. Click Create to open the Agent editor.

Start with a template when you want default content. Customize the Agent after you create it. To start from scratch, select AI Assistant. Clear the default content.

You can also create an Agent from a Product. Open the Product. Click Add Capability, then click New Agent. This creates the Agent and adds it as a Capability.

Configure your Agent

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

About

Use About to edit the Agent’s name, description, and icon. An Agent has no draft, active, paused, or archived lifecycle field. Product versions and Surface status affect availability. Connected Capabilities also control availability.

Model

Select the model that generates responses and handles reasoning. Every Runtype Agent runs on a model. If you need step-by-step logic that a Flow defines, attach that Flow to the Agent as a Flow tool (see Agent tools) so the model can call it, or dispatch the Flow directly instead of routing it through an Agent.

Agent Sandbox capabilities

An enabled config.sandbox currently supports the runtype-sandbox provider, ephemeral or conversation persistence, and the standard-4 instance size. Daytona, named persistence, and other sizes remain readable in stored configurations, but enabling or changing an unsupported configuration returns unsupported_sandbox_capability with the field path and supported alternatives.

Agent reads include sandboxCapabilityIssues for enabled unsupported settings. Unrelated edits and exports preserve the stored values. Before the next run, select a supported value or disable Sandbox. Agent Sandbox retention keeps its separate one-hour default; it does not inherit the defaults of the preview deployment tools.

Behavior

System prompt

The system prompt defines the Agent’s role, goals, constraints, and priorities. Describe the outcome that you want. Let the model choose the tool sequence when the path varies.

Use a system prompt such as the following:

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

Start from a built-in system prompt template such as Helpful Assistant, Customer Support, or Technical Expert.

Temperature

Use Temperature to control variation in responses. Agent configuration accepts values from 0 to 2. The dashboard control exposes values from 0 to 1. Lower values produce more consistent output. Higher values produce more variation.

Claude 5 models, such as claude-sonnet-5, and GPT-5 family models, such as gpt-5 and gpt-5-mini, do not support Temperature. Runtype omits the setting when it runs those models.

Safety

The Safety section controls tool approval and the Max tool calls limit.

Tool approval pauses execution before a tool runs and requires approval. Use it when a person must review an action before it happens. An approval request can include a short justification in Agent’s stated reason. Treat this text as context, not as a system guarantee. Review the tool name and parameters before you approve the call.

When tool approval is on, choose a scope:

• All tools: Require approval for every tool call.
• Only selected: Require approval for selected attached tools and Capabilities.

Add a custom pattern in Only selected. Use a wildcard such as mcp:* or builtin:* to match every tool of that type. The same patterns work in dispatch requests and code. For dispatch overrides, see dispatch-time approval overrides.

Approval rules match tool names. Renaming a tool clears its rule. An empty selection turns off tool approval when you save. Select at least one tool before saving.

To offer remembered grants, turn on Allow ‘always allow’. Supported approval interfaces then offer Always allow, Allow once, and Deny. When you select Always allow, Runtype remembers your decision. It skips the prompt for that tool on later runs. Authorization still applies. Tool access, ownership, and secrets do not change. The setting is off by default.

Slack and Telegram use channel approval prompts for Agent loop runs. These prompts offer one-time Approve and Deny choices. They do not offer Always allow or create a remembered approval.

SMS and iMessage have no approval buttons. For Agent loop runs on these Surfaces, reply to the approval question. Runtype adds a line with the exact tool and its parameters. It interprets your reply as an approval or a denial. Attach approval-required tools to an Agent loop Agent on an SMS or iMessage Surface to use reply-based approval. No additional setting is required.

For an ordinary Runtype Agent on Slack, Telegram, SMS, or iMessage, enable Agent loop and set Max turns to 2 or higher. A Managed external Agent already executes through an effective Runtime Agent Loop, so it does not need an authored Agent Loop or Max turns setting. Telegram, SMS, and iMessage still require their Surface’s inbound verification credential.

Single-pass Agents on messaging Surfaces stop the approval-gated path without showing a prompt that the Surface cannot resume. The same behavior applies to Surfaces without approval controls, such as email, WhatsApp, Discord, and generic messaging.

Unattended runs behave the same way and are refused before the Agent starts: Schedules, Batches, Evals, Webhooks, and API or JSON requests with no live caller have nobody to answer the prompt. Each one fails with an error naming the tool approval policy, and no gated tool runs. Remove tools.approval.require, or route the work through a Surface that can answer approvals.

Remembered approvals appear in the Remembered approvals card. Each entry shows the tool and its scope, such as a specific user or All users. Revoke an entry to show the approval prompt on the next run.

Set Max tool calls to limit tool calls in one turn. Agent configuration accepts values from 1 to 100. The dashboard control accepts values from 1 to 50.

Agent loop

Enable Agent loop to continue execution across multiple turns. Each turn can include model reasoning, tool calls, and tool results.

When Agent loop is enabled, configure these settings:

• Max turns: Agent configuration accepts values from 1 to 100. The dashboard control sets values from 2 to 20. The loop ends when the model finishes a turn or reaches this limit.
• Reflection: Enable periodic self-assessment and set the reflection interval.
• Cost budget (USD): Set the maximum spend for one execution. The runtime stops the execution when it reaches this limit.

Test with 5 to 10 max turns, then adjust the limit based on your results. Use a higher limit when the task requires additional iterations.

Context compaction

Context compaction is enabled by default. Before model calls, including calls after a tool batch, Runtype first reduces older tool output and then condenses older conversation content when needed. The stored transcript is not rewritten. The model receives a smaller view, so summaries can omit detail; keep critical requirements in the Agent’s instructions rather than relying only on earlier messages.

Configure contextManagement.compaction in the Agent configuration or override it for an execution:

In the dashboard, open the Agent editor’s Context section. Condense long conversations enables or disables compaction; Strategy selects automatic, provider-native, or summary behavior. Enter percentages directly: Condense at takes 85 for the API’s thresholdRatio: 0.85. A fixed input-token count overrides that percentage. Clearing a numeric field restores its displayed default. Recent tokens kept in full controls the retained tail, and Summary instructions specifies what the summary should preserve. Test agent uses your current edits, even before saving.

The separate Tool results controls govern spilling and masking. Keep every result disables masking only; it does not disable spilling or conversation compaction. Changing the compaction toggle does not change these tool-result settings. The editor keeps untouched settings inherited from platform defaults rather than saving a copy of every default.

1
{
2
  "contextManagement": {
3
    "compaction": {
4
      "enabled": true,
5
      "strategy": "auto",
6
      "thresholdRatio": 0.85,
7
      "retainRecentTokens": 8000,
8
      "instructions": "Preserve decisions, unresolved questions, and artifact references."
9
    }
10
  }
11
}

• enabled: false prevents new compaction. An existing valid conversation summary continues to be used; disabling compaction does not restore summarized history to the model. Tool-output spilling and pruning remain enabled.
• strategy: "auto" uses provider-native compaction only when both the routed executor and conversation surface support native history. Otherwise it uses a summary generated by the current model. Text-only messaging surfaces use summaries even with a native-capable model. "summary" selects summarization explicitly; "provider_native" also falls back to summarization when the route or surface cannot preserve native history.
• thresholdRatio controls when compaction starts relative to the usable context budget. thresholdTokens supplies an absolute token threshold instead. Triggering earlier leaves more room for new input, tool output, and the model’s answer.
• retainRecentTokens controls the recent content retained alongside a summary.
• instructions adds guidance for the summarizer. A separate compaction.model override is not yet supported.

Summary generation adds model calls, latency, and token usage. These calls count toward execution cost and the Agent loop’s cost budget. If a provider rejects the initial request for exceeding its context window before any output is streamed, Runtype can compact and retry once. Recovery can still fail; reduce the input or trigger compaction earlier rather than assuming an unlimited conversation fits.

The streaming context_notice event reports compaction activity. It is informational, not assistant text or an execution-completion event. Compaction manages the current conversation’s model context; it is separate from Memory, which stores information across conversations.

Error handling

The Error handling section controls what happens when the model fails or returns no text. Open its configuration modal and choose one mode:

• Continue on error: Skip the failure and continue the execution.
• Stop on error: Stop the execution when the model fails.
• Use fallbacks: Try alternatives before the execution stops.

Configure a fallback chain when you choose Use fallbacks. Runtype tries each fallback in order until one succeeds. Use these fallback types:

• Retry: Run the same model again.
• Different model: Switch to a backup model and optionally override temperature and maxTokens.
• Fixed message: Return a predefined reply without calling a model.

Select what triggers the fallback chain. Select The step errors when the model fails with a provider error, timeout, or thrown failure. Select The reply is empty when the model finishes without an error but returns no visible text. You can select both triggers.

Temporal awareness

Models do not receive elapsed-time context by default. The Agent’s temporal configuration adds two opt-in capabilities. These include a default time zone for the temporal tools and an elapsed-time notice between messages.

Configure these fields:

• timezone: Set the Agent’s default Internet Assigned Numbers Authority (IANA) time zone, such as America/New_York. Temporal tools use it when no explicit time zone is passed. They also use it when the conversation has no stored time zone.
• injectElapsed: Set this field to true to add a short “time has passed” notice at the start of a turn after a gap. The notice applies inside a conversation from the second message onward.
• elapsedThresholdSeconds: Set the minimum gap, in seconds, before Runtype adds the notice. The default is 30. Set it to 300 when you want to annotate gaps of several minutes.
• groundNow: Set this field to true to include the current date and time in the resolved time zone.

Runtype resolves the time zone in this order: the conversation’s stored time zone, the Agent’s default timezone, and UTC.

Memory

The Agent’s memory configuration stores information across conversations. When memory is enabled, Runtype automatically adds three memory tools: save_memory, recall_memory, and memory_summary. Runtype also records each user and assistant exchange in the background. The Agent can use these tools to recall facts from earlier conversations.

Configure these fields:

• enabled: Set this field to true to enable memory. The three memory tools become available automatically. Do not add them to the Tools list.
• profileTemplate: Set the profile scope that each execution reads and writes. If you omit this field, a saved Agent uses its own ID, {{_agent.id}}. This creates one shared bucket per Agent. Use {{_user.id}} for a Runtype account. A Product Tenant is a company or workspace shared by its users. Use {{_tenant.id}} for a Product Tenant. Use {{_endUser.id}} for an individual SaaS end user.
• injectSummary: This optional field defaults to true when memory is enabled. Runtype adds a profile summary to the system prompt on each turn. Set it to false to omit the summary for task Agents that do not need a profile overview.
• pointerScope: This optional field applies only to Agents that set a tenancyStrategy, where Runtype computes the namespace and ignores profileTemplate. Set it to "alias" or "version" to give each release alias or each version its own bucket. It defaults to "shared". On an Agent without a Tenancy Strategy the field does nothing, and validation reports MEMORY_POINTER_SCOPE_IGNORED. Key the template instead.

The profileTemplate resolves these variables:

The three release-pointer variables are absent on an execution that named no version selector, and {{_agent.alias}} is absent when the request pinned a bare versionId. Give any reference to them a fallback, such as {{_agent.alias || "live"}}, or memory switches off on those runs. By default a new version, a preview alias, and a pinned version all share one bucket. For when to key memory by the pointer and how to do it without disabling memory on ordinary traffic, see Memory namespaces and release pointers.

The injected summary includes standing preferences, recent decisions, and active tasks. Runtype caches the summary per profile, so it generates the summary once per profile.

If a profileTemplate variable cannot be resolved at run time, Runtype disables memory for that execution and logs a warning. It does not fall back to a shared bucket.

To override memory for one dispatch, include memory in the agentInput of a /v1/dispatch request. The per-call memory object accepts enabled, profileTemplate, injectSummary, and pointerScope. Use this option when you know the end-user identity only at dispatch time, or to send a CI run to its own bucket without editing the Agent. pointerScope matters here only when the saved Agent sets a tenancyStrategy; on any other Agent, override profileTemplate instead.

An inline dispatch Agent without a saved Agent ID must set an explicit profileTemplate. Without a saved Agent identity, the runtime cannot select a per-Agent default profile. Memory remains disabled until you set a profile scope.

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

Tools

Use the tools area to attach tools and subagents to your Agent.

Adding tools

To add tools, follow these steps:

1. In the Agent editor, click the tools area.
2. Click Add Tool or Configure Tools.
3. Select the tools to add.
4. Click Apply Changes.

The model selects tools from the attached set based on the task. You do not need to script the order.

Writing good tool descriptions

Tool descriptions give the model the information that it uses for tool selection. Include the following information in each description:

• What the tool does.
• When to use it.
• What it returns.

Use a description such as the following:

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

Use a vague description such as the following:

Searches stuff.

Write descriptions that identify the action, use cases, and result. Write for someone who has not used the tool before.

Subagents

Add other Flows or Agents as tools. The parent Agent can send focused subtasks to subagents with their own tool subset and context. Use this pattern when a workflow has specialized subtasks.

Test your Agent

To test your Agent, follow these steps:

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

The test panel shows tool calls and tool results. Use these details to tune the system prompt, tool selection, and loop settings.

Test realistic inputs, including edge cases. Refine the system prompt, tool selection, and loop settings based on the results.

Add your Agent to a Product

After you configure and test an Agent, add it to a Product so people can use it through connected Surfaces.

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

For more detail on Capabilities in a Product, see Adding capabilities to a product.

After you add the Agent, it is available through any Surface connected to that Product, including chat, the API, and Model Context Protocol (MCP) surfaces.

Best practices

Use these practices when you configure an Agent:

• Start with a template. Use a built-in template, then tailor it to your use case.
• Keep tools focused. Start with two or three tools. Add more when the task requires them. Fewer, well-described tools reduce ambiguity during selection.
• Write clear instructions. State the goals and constraints in the system prompt.
• Test iteratively. Try varied inputs and refine the Agent based on the results.
• Use Agent loop thoughtfully. Turn it on when the task needs multiple rounds. Set a Max turns limit and a cost budget.
• Set cost budgets. Use a cost budget to control spend for each execution.

Next steps

Continue with these guides:

• Agent versioning and publishing: manage drafts and published versions, and return to an earlier configuration.
• Manage agents as code: keep Agent definitions in your repository and converge them at deploy time.
• What are Surfaces?: connect Agents to user-facing channels.
• What are Agents?: review the Agent concept and execution model.
• Agent tools: configure tool types, descriptions, and subagent delegation.