Authoring agents

When the deployment enables Tembo Memory, Pydantic agents automatically receive managed Memory tools (memory_ask, memory_search, memory_entities, memory_report) at run time. No connections: entry is needed — do not add tembo-memory. Keep those tool names free of sidecar collisions.

The generic runtime blurb is not enough: an agent’s numbered procedure (“produce nothing else”) overrides it. Weave Memory into the procedure itself — memory_ask before acting on a person, account, deal, or thread; memory_report once per interesting item inspected, including ones not surfaced to a worklist. Entity ids are kind:name (person:jane@acme.com, org:acme); prefer person:<email> or {id, email} for people. A bare display name is stored as unknown:, not as a person. Skip bulk, billing, and thanks. Unavailable reads produce a warning, not an empty-knowledge answer; report writes return durable queued receipts for background delivery. See Connections for workspace sharing, setup, and outage behavior.

Agents are authored as files and changed through pull requests. You can write those files directly, but the usual path is to describe what you want and let TAS open the PR for you.

Editing files from Versions

Operators can edit an agent’s spec in Versions → Definition or an existing sidecar in Versions → Eval file. Choose Edit as draft, change the text, and select Save draft. Cancel discards the local edits. Selecting an older spec snapshot lets you use it as the starting point for a draft change; the snapshot itself stays unchanged.

Saving validates the file before submitting an exact replacement through the same asynchronous process as chat edits. Follow View progress to the task; the workspace’s PR or direct-commit policy determines how the change lands. Reload Versions after it lands to see the new repository draft. This requires a connected repository and the same coding-agent credentials as chat editing. Saving does not promote a numbered stable version; use Promote separately. Eval files remain repository sidecars, rather than part of stable snapshots.

Invalid content, changes to the agent’s name or framework, and files changed since the editor was opened are rejected. A conflict detected by the coding task also stops the replacement. Agents without eval files stay unchanged; the inline editor does not create one. Locked agents cannot be edited here.

Creating an agent from chat

Describe the agent you want — its job, its tone, the services it should use. TAS hands the request to the Tembo Coding Agent Platform, which writes the agent file and opens a pull request against your repo. Review and merge it; the agent then shows up in the Agents list. (This requires a Tembo API key in Settings.)

Regression evals are optional and default on. The create (and chat-to-edit / Improve) form asks whether to add a colocated eval sidecar. Leave it checked and the coding agent writes assertion cases TAS will run on the authoring PR and before Promote. Uncheck it to skip; agents without an eval file are not gated. See Agent evals.

If the description names a recurring cadence, TAS shows it as a suggested schedule after submitting the agent. It does not create an automation. After the commit lands, reload the Agents list (it should appear within a few seconds), test and verify it, then use Create suggested automation to save the schedule in a disabled state. Enable it from the agent’s Automation tab only when the agent is ready to run unattended.

Not sure what to ask for? Example Agents has ready-to-use, copy-paste prompts (email triage, ticket roundups, …) that adapt to whatever you’ve connected.

The agent file (Pydantic AgentSpec)

A minimal agent is a YAML file under agents/pydantic-agentspec/:

name: standup-summary
model: anthropic:claude-sonnet-5
description: Summarize yesterday's commits into a standup note.
instructions: |
  When invoked, summarize the team's activity in three bullet points.
  Be concise and factual.

Key fields:

name (required) — the slug identifier; must match the filename (name: foo → foo.yaml); lowercase letters, digits, hyphens. It’s the stable key for URLs, runs, and automations, so don’t change it after creation.
title (optional) — a free-text display name shown in the UI (e.g. title: "Inbox Triage"). When you create an agent you can type any name; the filename slug is derived from it and the text is saved as title. The UI falls back to name when there’s no title.
model (required) — provider:model, e.g. anthropic:claude-sonnet-5, anthropic:claude-opus-4-8, anthropic:claude-fable-5, openai:gpt-5.5, openai:gpt-4o-mini, or fireworks:accounts/fireworks/models/llama-v3p3-70b-instruct. For Fireworks, use the full model ID from its catalog. The provider’s key must be set in Settings → LLM Providers.
instructions (required) — the system prompt, usually a | block scalar.
connections: (optional) — external services the agent calls; see Connections.
tools_module: (optional) — a sibling Python file of deterministic tool functions; see Sidecar Python tools.
labels: (optional) — tags used for grouping and for scoping which Slack app or text-message number may launch the agent.
scaledown: (optional) — opt into ScaleDown prompt compression to cut frontier-model tokens (off / prompt / aggressive).
skills: (optional) — names of Skills to load, giving the agent reusable instructions/procedures on top of instructions.
Eval sidecar (optional) — a colocated <name>.eval.yaml file. TAS runs assertions on authoring PRs and blocks Promote until they pass; see Agent evals.
delivery: (optional) — describe where this agent intends to deliver its result and what durable evidence TAS can observe. The declaration is snapshotted on each run, so later edits do not rewrite output history.
```
delivery:
  note: Daily brief for the account team
  destinations:
    - key: tasks-inbox
      label: Tasks Inbox
      evidence:
        type: inbox_item
    - key: email
      label: Email
      evidence:
        type: tool_call
        tool: GMAIL_SEND_EMAIL
```
Destinations are agent-defined — use any stable key and human-readable label. Evidence can be an inbox_item produced by the run or a named tool_call. TAS records the tool name and success only; tool arguments and results remain unstored because they may contain secrets or personal data.

Only add delivery when the agent is actually expected to publish its result outside its own run. Omit it when the agent only returns output to its caller. delivery describes destinations and evidence; use output_schema when you need to control the response shape.

Evidence is scoped to the exact run carrying the declaration. If an orchestrator delegates delivery to a sub-agent, put delivery on the sub-agent that creates the inbox item or calls the delivery tool. Sub-agent evidence does not roll up into the orchestrator’s declaration.
model_settings: (optional) — a map of model knobs passed through to the model, e.g. max_tokens, temperature, parallel_tool_calls. TAS defaults parallel_tool_calls: false (so tools run one at a time unless you set it true) and, for Anthropic models, enables prompt caching — both overridable here.
```
model_settings:
  max_tokens: 6144
  temperature: 0.2
```
request_limit: (optional) — cap the number of model requests in a single run (Pydantic AI UsageLimits). Defaults to 50; lower it to bound cost/looping on a tool-heavy agent.
retries: (optional, int) — how many times a failing tool call may be retried within a run.
instrument: (optional, bool) — toggle Pydantic AI run instrumentation (OpenTelemetry spans) for this agent.

Your connected repo also carries an authoring guide (AGENTS.md and per-framework AGENT_GUIDE.md) that TAS keeps current — that’s the canonical, always-up-to-date field reference for coding agents.

Inspecting the definition

The agent’s Definition tab puts recent repository history above the static source. The full draft definition and sidecar tools module start collapsed with their format and line counts visible; expand either section to inspect or copy all of its source. Promoted definitions remain available from the version selector and the Versions tab.

Built-in run date and time

Every Pydantic agent has a get_run_datetime tool; no connection or agent file setting is required. Use it for relative date windows, date-based deduplication, and any task that depends on “today.” It returns the UTC instant when the run entered running, plus local date/time fields in an optional IANA timezone such as America/Los_Angeles. The instant stays fixed for the entire run, including runs that cross midnight.

Choosing a model

Model choice is a cost/reliability tradeoff:

Default to anthropic:claude-sonnet-5 for most agents, tools or not. It’s the most agentic Sonnet yet — decisive about when to act, so it doesn’t hedge (“would you like me to…”) the way earlier Sonnet and mini tiers do — with reasoning and tool use close to Opus 4.8 at lower cost.
Need more than Sonnet 5? Step up to anthropic:claude-opus-4-8, and to anthropic:claude-fable-5 (Anthropic’s most capable, Mythos-class) for the hardest reasoning and long-horizon agentic work — reach for Fable only when Opus 4.8 isn’t enough.
Cheaper, simpler jobs. anthropic:claude-haiku-4-5 and the mini tiers are fine for no-tools or high-volume work with a single, well-defined job and imperative instructions; they tend to hedge on tool calls, so prefer Sonnet 5 for anything that declares connections:. Compare cost side-by-side on the Runs page.

ScaleDown prompt compression

ScaleDown is an optional prompt-compression layer: bulky context is routed through a small model that rewrites it to far fewer tokens while preserving the query, so you spend fewer tokens on the expensive frontier model. It’s opt-in per agent and a no-op unless a workspace ScaleDown API key is set under Settings → LLM Providers.

Enable it with the scaledown: field:

name: long-research
model: anthropic:claude-opus-4-8
scaledown: prompt          # off (default) | prompt | aggressive
instructions: |
  …

Modes:

off (default, or field absent) — no compression; runs are byte-identical to having no key.
prompt — compress the static instructions once at startup. The safe, recommended default: it’s lossy only on your own system prompt, adds no per-turn latency, and is cache-friendly — the compressed instructions are identical every turn, so Anthropic prompt caching still hits (on a smaller prefix).
aggressive — also compress bulky history blocks (large tool outputs, user context) on each turn. Best for long, tool-heavy, cost-sensitive runs. Each block is compressed once and frozen (memoized by content), so repeated turns send identical bytes and prompt caching keeps working instead of thrashing. Message structure (tool calls / tool results) and the most recent turn are left untouched.

Object form tunes it:

scaledown:
  mode: aggressive
  rate: auto             # ScaleDown compression rate
  min_tokens: 400        # only compress blocks larger than this

Notes

Lossy by design. Compression drops detail to save tokens. Start with prompt; move to aggressive only where token cost matters and you’ve confirmed quality holds.
Best-effort. If ScaleDown is unreachable or errors, the original text is used — a run never fails because of compression.
Where to see it. Token savings are logged in the instance/container logs ([scaledown] N → M tokens); they are not yet surfaced in the run-detail UI.

Iterating

Chat-to-edit — probe the live draft in the agent chat surface, then submit a change request that opens a PR. See Agent lifecycle.
Improve the Agent from any run turns feedback into a PR — see Improvements.
Promote a draft to a stable version when you’re happy with it; automated runs serve stable by default. See Agent lifecycle → promoting.

Your agent list, stars, and forking

All members’ agents live in one repo, so the agents list can get crowded. To keep your day-to-day view tidy:

Star any agent with the ☆ on its row. Stars are personal; they don’t change the shared repo or the labels: taxonomy. Use separate Owner (Me or Others) and Starred (True or False) filters to combine ownership and star status however you need.
Search finds agents by name, description, label, model, or connection. Rows default to most recently run (agents with no run history come last); use the Sort menu for name, status, trailing-30-day runs/cost/success, or recent activity. Click anywhere on a live-agent row except its explicit controls to open it. The trailing-30-day count, average cost, and success rate stay hidden until the agent has at least one run in that window; missing model or cost values are left blank instead of showing placeholder dashes.
Add structured filters from Add filter. Each active filter is an editable pill, and the list updates immediately when you change or remove it. Click is to switch a filter to is not; list-valued filters accept multiple selections and match any selected value. Alongside owner, star status, status, label, model, and connection filters, you can filter agents by the observed Orchestrator or Sub-agent role, or show only the sub-agents called by a particular orchestrator. These relationships come from run history; they are not fields in the agent spec, and an agent can match both roles in a nested workflow.
The built-in All and Mine views are always available and cannot be renamed or deleted. Changing their filters marks the view Unsaved; choosing Save creates a custom view without changing the built-in. Views appear as pills above search and sort; when space is limited, additional views move into the more menu.
Choose New view to name and save the current search, filters, and sort. Personal views are visible only to you; shared views are available to every member of the workspace. You can keep editing filters while naming a view and watch the result list update before you save it. Changing an owned saved view keeps it selected, marks it Unsaved, and reveals Save so you can update it in place. Customizing a shared view that you cannot edit creates a custom copy instead. Use Edit view to rename a custom view or change its visibility.
Fork an agent (the Fork button on its page) to make your own editable copy. The copy is named with an owner prefix — sales-gen forked by ryw becomes ryw.sales-gen — so two people can each keep their own without a name collision, and the fork is owned by you (so it shows in your default list). A forked tool-using agent shares the original’s tools_module: file (same folder) until you change it. Forking copies the spec verbatim; edits go through the usual PR flow.

The optional <handle>. prefix is the only place a dot is allowed in an agent name — plain names stay kebab-case (a-z0-9 and hyphens).

Choosing model effort

Open an agent’s Versions → Definition → Model effort to see its current draft effort and choose a supported level without editing YAML. The agent header also shows the draft effort, which can differ from the promoted stable version.

Provider default leaves effort unset. Defaults vary by model: Sonnet 5 and 5.5 default to High; Haiku 5.5 and Opus 5.5 default to Medium. On OpenAI models, None is an explicit value and is separate from Provider default.

The October 10, 2026 review adds GPT-6.1 Sol, GPT-6 Sol/Luna, and GPT-5.6 Sol/Terra/Luna with a Medium provider default and Maximum effort. GPT-6.1 Sol supports Low through Maximum, but not None or Minimal; the other listed models additionally support None. The catalog also recognizes the exact GPT-5.5 (2026-04-23), GPT-5.4 (2026-03-05), and GPT-5.4 Mini/Nano (2026-03-17) snapshots documented by OpenAI.

These models are verified against Pydantic AI 2.55.0’s Responses adapter, which openai: selects in that version. GPT-6 Astra and GPT-6.1 Sol require Responses for tool calling; GPT-6 Sol/Luna only support Chat Completions tool calling at None effort. An older deployment that resolves openai: to Chat Completions cannot use all these combinations. GPT-6 Astra has verified token prices but no effort dropdown: the checked documentation lists its effort levels without establishing a provider default. Explicit authored settings remain intact. See the OpenAI model guide and model-specific documentation.

Lower effort can reduce token usage and latency; higher effort can improve difficult tasks. It does not change the per-token price, and savings depend on the task. Compare runs and eval results before promoting an effort change.

Save effort as draft follows the same repository update process as chat and inline edits. Follow View progress, then reload after the change lands. Promote the draft separately for schedules, Slack, and other stable runs. Editing requires operator access, an unlocked agent, a connected repository, and coding-agent credentials. Read-only users can see the configured value.

Options come from a version-specific, verified catalog. For example, Sonnet 4.6 supports Low, Medium, High, and Maximum; Sonnet 5/5.5 and Haiku 5.5 also support Extra high. Models without verified options retain their raw settings and do not receive a dropdown. Advanced thinking controls or unrecognized effort values are labeled Custom and remain editable through Edit as draft.

The saved provider settings are model_settings.anthropic_effort for Anthropic and model_settings.openai_reasoning_effort for OpenAI. Other settings and YAML comments are preserved; existing agents are not assigned a new effort automatically.