# "Agents" _Path: en/framework/agents_ > "Define and run Wippy agents with tools, streaming, delegates, traits, memory, and custom resolution." ## Table of Contents - Agents ## Content # Agents The `wippy/agent` module defines agents declaratively and runs them through a context and runner. Agents can use tools, stream responses, delegate work, apply traits, and recall memory. This page is an API primer with composable reference snippets, not a standalone tutorial. The snippets assume an existing Wippy project, a registered LLM model and provider, configured provider credentials, and the agent, tool, or resolver entries referenced by each example. Later snippets build on variables such as `ctx`, `runner`, and `conversation` created in earlier sections. For a complete runnable project, follow [Build an LLM Agent](tutorials/llm-agent.md). ## Setup Add the module to your project: ```bash wippy add wippy/agent wippy install ``` The agent module declares its `wippy/llm` dependency itself. Add the agent dependency to source when it is not already present: ```yaml version: "1.0" namespace: app entries: - name: dep.agent kind: ns.dependency component: wippy/agent version: "*" ``` ## Agent Definitions Agents are registry entries with `meta.type: agent.gen1`: ```yaml entries: - name: assistant kind: registry.entry meta: type: agent.gen1 name: assistant title: Assistant comment: A helpful chat assistant prompt: | You are a helpful assistant. Be concise and direct. Answer questions clearly. model: gpt-4o max_tokens: 1024 temperature: 0.7 ``` ### Agent Fields | Field | Type | Description | |-------|------|-------------| | `meta.type` | string | Must be `agent.gen1` | | `meta.name` | string | Agent identifier | | `prompt` | string | System prompt | | `model` | string | Model name or class | | `max_tokens` | number | Maximum output tokens (default `512`) | | `temperature` | number | Optional sampling temperature; omitted by default, with range and support determined by the provider | | `thinking_effort` | number | Forwarded to the model only when `> 0` (provider-defined scale) | | `tools` | array | Tool registry IDs | | `traits` | array | Trait references | | `delegates` | array | Delegate agent references | | `memory` | array | Static memory items (strings) | | `memory_contract` | table | Dynamic memory configuration | | `agent_options` | table | Host options, including `checkpoint`, `turn_context` and loop settings | ## Agent Context Create an agent context, configure it as needed, and then load an agent: ```yaml imports: agent_context: wippy.agent:context prompt: wippy.llm:prompt ``` ```lua local agent_context = require("agent_context") local ctx = agent_context.new() local runner, err = ctx:load_agent("app:assistant") if err then error("Failed to load agent: " .. tostring(err)) end ``` ### Context Methods | Method | Description | |--------|-------------| | `agent_context.new(options?)` | Create new context | | `:add_tools(specs)` | Add tools at runtime | | `:add_delegates(specs)` | Add delegate agents | | `:configure_delegate_tools(config)` | Configure how delegates expose themselves as tools | | `:set_memory_contract(config)` | Configure dynamic memory | | `:set_context_merger(fn)` | Provide a function to merge runtime context updates | | `:update_context(updates)` | Update runtime context | | `:load_agent(spec_or_id, options?)` | Load and compile agent, returns runner | | `:switch_to_agent(id, options?)` | Switch to different agent, returns `(boolean, string?)` | | `:switch_to_model(name)` | Change model on current agent, returns `(boolean, string?)` | | `:get_current_agent()` | Get current runner | | `:get_config()` | Return a summary of the context configuration | ### Context Options ```lua local ctx = agent_context.new({ context = { session_id = "abc", user_id = "u1" }, delegate_tools = { enabled = true }, enable_cache = true, }) ``` | Option | Description | |--------|-------------| | `context` | Base runtime context forwarded to tools and delegates | | `delegate_tools` | Default delegate-tool configuration (overridden by `configure_delegate_tools`) | | `enable_cache` | Prompt cache marker setting for Claude models. The current implementation always enables markers, including when this option is `false`. | ### Loading by Inline Spec Load an agent without a registry entry: ```lua local runner, err = ctx:load_agent({ id = "inline-agent", name = "helper", prompt = "You are a helpful assistant.", model = "gpt-4o", max_tokens = 1024, tools = { "app.tools:search" }, }) ``` ## Running Steps The runner executes one agent step from a prompt-builder conversation: ```lua local prompt = require("prompt") local conversation = prompt.new() conversation:add_user("What is the capital of France?") local response, err = runner:step(conversation) if err then error(tostring(err)) end print(response.result) ``` ### Step Options ```lua local self_pid, pid_err = process.pid() if pid_err then error("Failed to get process PID: " .. tostring(pid_err)) end local response, err = runner:step(conversation, { context = { session_id = "abc" }, stream_target = { reply_to = self_pid, topic = "stream" }, tool_call = "auto", }) if err then error("Agent step failed: " .. tostring(err)) end ``` | Option | Type | Description | |--------|------|-------------| | `context` | table | Runtime context merged with agent context | | `stream_target` | table | Streaming: `{ reply_to, topic }` | | `tool_call` | string | `"auto"`, `"any"`, `"none"`, or a tool name | | `context_id` | string | Conversation ID for LLM usage tracking | | `route` | table | Previous response's `route_pin`, retained for the current turn | | `drop_stale_thinking` | boolean | Strip thinking bound to an earlier system/tool prefix | | `thinking_is_current` | function | Optional `(message, fingerprint) -> boolean` replacing the fingerprint comparison | | `checkpoint` | table | `{ token_threshold, compact }`; callback returns a replacement conversation builder | | `cancel` | channel | Host closes it to cancel in-flight generation | ### Step Response | Field | Type | Description | |-------|------|-------------| | `result` | string | Generated text | | `tokens` | table | Token usage | | `finish_reason` | string | Stop reason | | `tool_calls` | table? | Tool calls to execute | | `delegate_calls` | table? | Delegate invocations | | `metadata` | table? | Provider metadata, including `thinking_blocks` and `content_positions` | | `context_notes` | array? | Positional notes sent after the supplied conversation and before the output | | `prefix_fingerprint` | string? | SHA-256 of the system text and tool definitions actually sent | | `route_pin` | table? | Route retained after fallback, or the pin passed to this step | Pass `response.route_pin` back as `route` on later steps of the same turn, and clear it for a new turn. This keeps tool results on the route that produced their calls after a fallback. Closing `cancel` returns a stopped response with any text streamed so far and `finish_reason = "cancelled"`. ### Persisting Step Context Persist `context_notes` in order after the supplied conversation and before the assistant text or calls. These developer messages carry `metadata.preserve_position = true`; replay their content and metadata unchanged. `context_notes` replaces the earlier `memory_prompt` response field. Discard notes when discarding the step's output. Recall cooldown reads `metadata.memory_ids` from the persisted notes. Store `prefix_fingerprint` as `metadata.prefix_fingerprint` on assistant rows carrying thinking, together with `metadata.thinking_blocks` and any `metadata.content_positions`. Set `drop_stale_thinking = true` on subsequent steps. The runner removes blocks through the last stale message, including messages without a fingerprint. It works on copies and recomputes the fingerprint if a checkpoint replaces the conversation. The fingerprint covers the compiled system prompt, ordinary conversation system text and provider-visible tool definitions. It excludes the model and registry-only metadata. It reflects the Claude/Bedrock prefix; equality on other drivers is necessary but does not prove identical wire input. Edits to earlier conversation messages are not detected. Hosts with a checkpoint epoch can supply `thinking_is_current(message, fingerprint)` to check both. The current tool round keeps its thinking, with stale blocks marked for the driver to bind or omit. An older stale turn with an unanswered call fails before dispatch. See [thinking block binding](./llm.md#thinking-blocks-across-agents) for provider handling. ### Runner Stats ```lua local stats = runner:get_stats() -- stats.id, stats.name, stats.total_tokens ``` ## Tool Definitions Tools are `function.lua` entries with `meta.type: tool`. Define them in a separate `_index.yaml`: ```yaml version: "1.0" namespace: app.tools entries: - name: calculate kind: function.lua meta: type: tool title: Calculate input_schema: | { "type": "object", "properties": { "expression": { "type": "string", "description": "Math expression to evaluate" } }, "required": ["expression"], "additionalProperties": false } llm_alias: calculate llm_description: Evaluate a mathematical expression. source: file://calculate.lua modules: [expr] method: handler ``` ```lua local expr = require("expr") local function handler(args) local result, err = expr.eval(args.expression) if err then return { error = tostring(err) } end return { result = result } end return { handler = handler } ``` ### Tool Metadata | Field | Type | Description | |-------|------|-------------| | `meta.type` | string | Must be `tool` | | `meta.input_schema` | string/table | JSON Schema for tool arguments | | `meta.llm_alias` | string | Name exposed to the LLM | | `meta.llm_description` | string | Description exposed to the LLM | | `meta.exclusive` | boolean | If true, cancels concurrent tool calls | ### Referencing Tools in Agents List tool registry IDs in the agent definition: ```yaml - name: assistant kind: registry.entry meta: type: agent.gen1 name: assistant prompt: You are a helpful assistant with tools. model: gpt-4o max_tokens: 1024 tools: - app.tools:calculate - app.tools:search - app.tools:* # wildcard: all tools in namespace ``` Tools can also be referenced with custom aliases and context: ```yaml tools: - id: app.tools:search alias: web_search context: api_key: "${SEARCH_API_KEY}" ``` ## Tool Execution When an agent step returns `tool_calls`, execute them through the tool caller. Declare its import and the `json` module on the calling entry: ```yaml modules: [json] imports: tool_caller: wippy.agent.tools:caller ``` This loop handles registered tools; a host using delegates must also settle `delegate_calls`. ```lua local json = require("json") local tool_caller = require("tool_caller") local function execute_and_continue(runner, conversation) local caller = tool_caller.new():set_strategy(tool_caller.STRATEGY.PARALLEL) local route_pin = nil while true do local response, err = runner:step(conversation, { route = route_pin, drop_stale_thinking = true, }) if err then return nil, err end if response.truncation_reason then return nil, "Agent output was truncated" end route_pin = response.route_pin for _, note in ipairs(response.context_notes or {}) do conversation:add_message(note.role, note.content, note.name, note.metadata) end local metadata = response.metadata or {} metadata.prefix_fingerprint = response.prefix_fingerprint conversation:add_assistant(response.result or "", metadata) local tool_calls = response.tool_calls if not tool_calls or #tool_calls == 0 then return response.result, nil end -- Keep the response's calls together, then append results in call order. for _, tc in ipairs(tool_calls) do conversation:add_function_call(tc.name, json.encode(tc.arguments), tc.id, { provider_metadata = tc.provider_metadata, }) end local validated, validation_err = caller:validate(tool_calls) if validation_err then return nil, validation_err end local results, execute_err = caller:execute({}, validated) if execute_err then return nil, execute_err end for _, tc in ipairs(tool_calls) do local result = results[tc.id] local result_str = json.encode(result.error and { error = tostring(result.error) } or result.result) conversation:add_function_result(tc.name, result_str, tc.id) end end end ``` ### Tool Call Fields | Field | Type | Description | |-------|------|-------------| | `id` | string | Unique call identifier | | `name` | string | Tool name (alias or llm_alias) | | `arguments` | table | Parsed arguments | | `registry_id` | string | Full registry ID for execution | | `provider_metadata` | table? | Pass unchanged in `add_function_call` options | The caller validates calls and applies execution context. Hosts can configure wrappers with set_tool_wrappers(runner.tool_wrappers) and supply their refs with set_wrapper_context(...). Its default strategy is SEQUENTIAL; select PARALLEL to run a batch concurrently. A result of { success = false, error = "non-empty text" } sets ToolExecResult.error while preserving the original result. An error field alone remains ordinary result data. ### Result Listener Register a listener to persist results as calls finish: ```lua local caller = tool_caller.new():set_strategy(tool_caller.STRATEGY.PARALLEL) caller:set_result_listener(function(call_id, result) local _, err = store:save_observation(call_id, result) if err then return nil, err end end) ``` Here `store:save_observation` is the host's persistence function. The listener receives each call ID once, including validation failures, tool errors and cancellation, before `after_execute` wrappers. Parallel delivery follows completion order; sequential delivery finishes before the next call starts. The listener runs synchronously, so Stop waits for it to return. Keep it short and do not mutate the result. Raising or returning a non-nil second value fails delivery. The caller cancels running calls, starts no more, skips `after_execute`, and returns `nil, error` naming the failed ID. Already accepted results remain accepted. `set_result_listener(nil)` removes the listener. Hosts can pass a cancel channel as the third argument to `execute(context, validated, cancel)`. For how agent tool access and observability are secured, see the [Security Model](concepts/security-model.md). ## Attention context and UI actions When a user message contains a validated `wippy.attention` version 1 through 4 attachment, the prompt builder renders bounded candidates into the same user-role turn. The rendered block is marked `untrusted_user_observation`; labels, accessible text, and values are data and cannot supply model instructions. Unknown attachment kinds or versions remain inert until a handler is registered. Prompt rendering has its own byte budget and does not mutate the persisted attachment. Files attached to a user message are listed to the model by file name, type, size and ID. Their content is never inlined as an image. Image content reaches the model only through an approved `wippy.attention.visual` capture, described in [Visual capture](#visual-capture). ### Attention trait and tools Add `wippy.agent.traits:attention` to an agent to give it the Attention tools. All of them are private tools in the `wippy.agent.tools` namespace. Reads work with automatic attachment, message-context capability and overlay permission off. An incoming attachment does not grant tools. Keep the agent's existing model, prompt and unrelated traits. Add the reusable trait as one additional item: ```yaml traits: - id: wippy.agent.traits:attention ``` The trait supplies its read guard and tools. A bare standalone agent runner does not create a browser connection; live reads also need the Session broker and a turn bound to an authenticated Host tab. See the [Attention quickstart](../frontend/web-host/attention-quickstart.md) for a full agent entry, Host configuration and public package examples. The nine read tools inspect the current interface of the Host tab that submitted the turn: | Tool | Example arguments | Purpose | |---|---|---| | `attention_find_semantic` | `{"role":"button","name":"Save"}` | Match `role`, `name`, `text` or `resource_id` across the permitted tree. | | `attention_find_css` | `{"selector":"button","root":ref}` | Query one known document or shadow root. | | `attention_get_node` | `{"node_id":"returned-canonical-id"}` | Resolve one known canonical node. | | `attention_get_tree` | `{"scope":ref,"limit":16,"depth":2}` | Read a bounded subtree page. | | `attention_get_geometry` | `{"node":ref}` | Read geometry, coordinate space and quality. | | `attention_get_cursor` | `{}` | Read the latest pointer observation. | | `attention_get_focus` | `{}` | Read the focused target. | | `attention_get_selection` | `{}` | Read selected text and both endpoint paths. | | `attention_hit_test` | `{"x":100,"y":120}` | Inspect a point, by default with a 20 CSS-pixel radius and a 5-pixel grid. | In the examples, `ref` is the complete returned `NodeRef` with `host_instance_id`, `node_id`, `mount_id` and `generation`. The older `attention_inspect` tool was removed; the explicit read tools above replace it. `attention_context_set` turns automatic pointing context on or off for the current Session. It takes a required boolean `enabled` and an optional `expected_revision`. The trait instructs the agent to call it only when the user requests a change. There is no additional confirmation prompt. The setting belongs to the Session, so it stays in effect after the user switches to another agent. The four action tools ask the user to clarify or capture a target through the current authenticated Host connection: | Tool | Purpose | Targets | |---|---|---| | `ui_action_highlight` | Highlight candidate rectangles. | 1 to 32 | | `ui_action_confirm` | Ask whether a supplied candidate is the intended one. | 1 to 32 | | `ui_action_select` | Ask the user to select a candidate, or to select an arbitrary area when there are no targets and `capture_region: true`. | 0 to 32 | | `ui_action_capture_visual` | Ask the user to approve an image of a target, region or viewport. The `capture` object sets `scope` (`target`, `region` or `viewport`), `region`, `allow_adjustment`, `allow_viewport_choice` and `format` (`image/png` or `image/webp`). | 1 to 32 | The action tools and `attention_context_set` are exclusive, so each one cancels concurrent tool calls. See [agent clarification actions](../frontend/web-host/attention-context.md#agent-clarification-actions) for every argument and default. ### Read limits and history Semantic search and CSS search are separate modes; CSS requires one canonical document or shadow-root reference. Search returns at most eight matches and tree pages at most 32 nodes. Private results use `wippy.attention.model.v1`, preserve complete returned ancestry through local dictionaries, and are capped at 8 KiB. The trait guard admits one read per batch and four attempted reads per user turn, including invalid and refused attempts. Two invalid attempts end repair. It refuses reads when trusted history cannot establish the turn boundary. A refused call keeps the model's own call ID, tool name and arguments. The refusal reason travels to the tool in its execution context, and the tool returns a `rejected` result without contacting the Host. Unrelated tools in a mixed batch keep their normal behavior. These limits are not a global provider-generation or cost limit. See [the complete limits](../frontend/web-host/attention-context.md#canonical-inspection-and-agent-tools). Session stores each compact read result in private function history. Later model generations can reuse it while it remains valid. A result expires after 30 seconds, on a later user turn, after a completed browser action, or when a newer read replaces the same query. Tree reads also become stale when a later read reports a changed tree revision. Geometry reads use the geometry revision; point reads use both. Cursor, focus and selection use query replacement rather than the shared observation revision. Withdrawal uses existing `metadata.stale` behavior and preserves valid tool-call/result pairs. The result stays stored, but the model receives a stale-result notice instead of the old observation. Read lifetimes are measured from the time the server received the result, not from browser clocks. Immutable automatic attachments leave the model view after expiry, a later user turn, a fresh usable read or a completed browser action. Their stored content and hashes remain unchanged. ### Target references Each item of an action tool's `targets` array is an immutable target reference containing the snapshot, target, Host instance, mount ID and generation, path digest, rectangle, and optional label. It contains no capability or bearer token. The prompt renderer exposes this object as a candidate's `action_ref`, and a read that returns exactly one actionable node exposes it as `target_ref`. The agent must copy that exact object verbatim as one item of the tool's `targets` array, and must not build one from IDs, labels or coordinates. Tool arguments can also include a prompt of at most 512 characters and independent pointer and keyboard permissions. A zero-target `select` request is valid only with `capture_region: true`. Here `capture_region` enables Host-owned arbitrary area selection; it does not authorize screenshot capture. The tools receive ephemeral `ui_action_runtime` context only at exact registered tool execution. The context is excluded from validated tool-call records, wrappers, persistence, history, and model-visible payloads. The session broker rejects a tool when the current turn has no eligible Host connection, when interactive actions are disabled, or when its target belongs to another Host instance. Read-only inspection has independent authority. Requests bind to the Host tab that submitted the current turn; reconnect requires a fresh authenticated binding and cannot replay an expired request. The Session plugin is the sole WebSocket inbox owner. It validates incoming action results and routes each accepted result to a private per-call mailbox. Framework tools wait on that mailbox rather than subscribing to WebSocket topics themselves. The tool path waits for one terminal Host result. Its status is `selected`, `confirmed`, `prepared`, `cancelled`, `denied`, `rejected`, `expired`, `stale`, `disconnected`, `permission-denied`, `unavailable` or `error`. See [terminal statuses](../frontend/web-host/attention-context.md#terminal-statuses) for the meaning of each one. The broker permits one pending action per session, caps expiry at 120 seconds, and accepts only the first correctly correlated terminal result. ### Visual capture `ui_action_capture_visual` opens explicit Host approval and prepares a removable ordinary composer file. It never sends the message. Target or region capture is the default, and viewport capture is offered only when the request sets `allow_viewport_choice`. The approved image is uploaded as an ordinary file, so the application's upload type must accept `image/png`, and `image/webp` when that format is requested. When the user later sends a message that still includes the file, the Host adds one `wippy.attention.visual` attachment that references the upload. This happens even when automatic pointing context is off. Semantic Attention attachments contain no screenshot bytes or upload references. The session upload authorizer and byte resolver are implemented through the content-provider contract. Before persistence, the session layer validates reference structure, session binding, expiry, media type, size, and digest, then authorizes the reference and verifies the resolved bytes. An attached reference that cannot pass these checks rejects the complete send atomically; it is not silently removed to persist a semantic-only message. When rendering an accepted message, the framework emits image input only when an authorized `visual_resolver` returns bytes that pass media-type, size, and SHA-256 checks. Later expiry, denied access, an unavailable resolver, or invalid bytes omits the image and returns a render diagnostic without changing the persisted message; other valid semantic context remains renderable. Deployments must verify capture, redaction, ordinary-file authorization, expiry and orphan cleanup independently. A byte resolver alone does not establish those behaviors. ### Errors during a turn A model or provider error ends only the current turn. The user sees the error and can send the message again in the same Session. If the Session process stopped because of a crash, the next message reopens it. See [Web Host Attention Context](../frontend/web-host/attention-context.md#agent-clarification-actions) for the overlay behavior and [Relay](./relay.md#attention-ui-action-routing) for connection targeting. ## Streaming Stream agent responses through `stream_target`: ```lua local TOPIC = "agent_stream" local function stream_step(runner, conversation) local stream_ch, listen_err = process.listen(TOPIC) if listen_err then return nil, nil, listen_err end local function finish(text, response, err) local ok, cleanup_err = process.unlisten(stream_ch) if not ok then cleanup_err = cleanup_err or "Failed to remove agent stream listener" if err then return text, nil, tostring(err) .. "; cleanup failed: " .. tostring(cleanup_err) end return text, nil, cleanup_err end if err then return text, nil, err end return text, response, nil end local self_pid, pid_err = process.pid() if pid_err then return finish("", nil, pid_err) end local done_ch = channel.new(1) coroutine.spawn(function() local response, err = runner:step(conversation, { stream_target = { reply_to = self_pid, topic = TOPIC, }, }) done_ch:send({ response = response, err = err }) end) local full_text = "" local step_result = nil local stream_done = false local stream_err = nil while true do local cases = {} if not stream_done then table.insert(cases, stream_ch:case_receive()) end if not step_result then table.insert(cases, done_ch:case_receive()) end local result = channel.select(cases) if not result.ok then return finish(full_text, nil, "Agent stream closed before completion") end if result.channel == done_ch then step_result = result.value if step_result.err then return finish(full_text, nil, step_result.err) end if stream_done then return finish(full_text, step_result.response, stream_err) end else local chunk = result.value if chunk.type == "chunk" then local content = chunk.content or "" print(content) full_text = full_text .. content elseif chunk.type == "error" then stream_done = true stream_err = chunk.error and chunk.error.message or "Agent stream failed" elseif chunk.type == "done" then stream_done = true end if stream_done and step_result then return finish(full_text, step_result.response, stream_err) end end end end ``` The stream uses the same chunk types as direct LLM streaming: `"chunk"`, `"thinking"`, `"tool_call"`, `"error"`, `"done"`. Use coroutine.spawn to run runner:step() in a separate coroutine so you can receive stream chunks concurrently. Use channel.select to multiplex the stream and completion channels. ## Delegates Agents can delegate to other agents. Delegates appear as tools to the parent agent: ```yaml - name: coordinator kind: registry.entry meta: type: agent.gen1 name: coordinator prompt: Route questions to the right specialist. model: gpt-4o max_tokens: 1024 delegates: - id: app:code_agent name: ask_coder rule: for programming questions - id: app:math_agent name: ask_mathematician rule: for math problems ``` Delegate calls appear in `response.delegate_calls`: ```lua local response, err = runner:step(conversation) if err then error("Delegate step failed: " .. tostring(err)) end if response.delegate_calls then for _, dc in ipairs(response.delegate_calls) do -- dc.agent_id - target agent registry ID -- dc.name - delegate tool name -- dc.arguments - forwarded message end end ``` Delegates can also be added at runtime: ```lua ctx:add_delegates({ { id = "app:specialist", name = "ask_specialist", rule = "for domain questions" }, }) ``` ## Traits Traits are reusable definitions that contribute prompts, tools, and behavior to agents: ```yaml - name: assistant kind: registry.entry meta: type: agent.gen1 name: assistant prompt: You are a helpful assistant. model: gpt-4o traits: - wippy.agent.traits:time_aware - id: app:custom_trait context: key: value ``` ### Built-in Traits | Trait | Description | |-------|-------------| | `wippy.agent.traits:time_aware` | Declares per-turn time context for the host to render and store | | `wippy.agent.traits:attention` | Adds the Attention read tools, `attention_context_set` and the UI action tools. See [Attention context and UI actions](#attention-context-and-ui-actions). | The `time_aware` trait accepts context options: ```yaml traits: - id: wippy.agent.traits:time_aware context: timezone: America/New_York time_format: "2006-01-02 15:04 MST" ``` The build function contributes `agent_options.turn_context.time = { timezone, format }` and no prompt text. `timezone` defaults to UTC; `time_format` is an optional Go time layout. The legacy `time_interval` is ignored. Hosts render once per user turn with `wippy.agent:turn_context` and persist the note after the user message: ```yaml modules: [time] imports: turn_context: wippy.agent:turn_context ``` ```lua local turn_context = require("turn_context") local time = require("time") local note, err = turn_context.render(runner.agent_options, time.now()) if err then return nil, err end if note then conversation:add_system(note, { preserve_position = true }) end ``` Keep this note unchanged on later steps. Session and Dataflow hosts persist it automatically. Unknown or empty timezones and invalid formats fail rendering; a malformed `time_format` fails trait compilation. The `wippy/session` module, version 0.6.3 or newer, provides two traits for live session input: | Trait | Description | |-------|-------------| | `wippy.session.traits:steering` | Defaults the active agent to accepting messages while a turn is running. | | `wippy.session.traits:input_control` | Grants `set_session_input_policy`, which can change the current turn or persistent session policy. It does not enable steering by itself. | See [Sessions](./sessions.md) for policy order, tool scopes, Stop behavior, and the public interaction state. ### Custom Traits Traits are registry entries with `meta.type: agent.trait`. They can contribute: - **prompt** - static text appended to the system prompt - **build_func_id** - function called at compile time to contribute tools, prompts, delegates - **prompt_func_id** - function called at each step whose returned system text must stay stable across the conversation - **step_func_id** - function called at each step for side effects Changing per-step context belongs in persisted positional notes. Lifecycle messages from `activate` and `before_step` must use `developer` or `system`; Session and Dataflow reject other roles. A failed prompt function fails the step before provider dispatch. ### Behaviors and Compaction Put `behaviors` directly on the trait registry entry, alongside `meta`; do not nest it under `data`. Attach a trait to set per-agent checkpoint defaults: ```yaml entries: - name: compaction kind: registry.entry meta: type: agent.trait name: Compaction behaviors: compaction: handles: [checkpoint] checkpoint: token_threshold: 12000 model: class:fast temperature: 0.2 max_tokens: 3000 - name: assistant kind: registry.entry meta: type: agent.gen1 name: assistant prompt: You are a helpful assistant. model: gpt-4o traits: [app:compaction] agent_options: checkpoint: token_threshold: 16000 ``` This behavior has no checkpoint handler and configures the host's default summarizer. Only behaviors without a checkpoint handler (`handlers.checkpoint` or the shared `handler`) promote `model`, `temperature`, Session's `max_tool_result_chars`, `max_conversation_chars`, `max_tool_results`, `max_tool_results_chars`, and Dataflow's `max_row_chars` into `agent_options.checkpoint`. With a handler, those keys remain local to its binding. The keys `enabled`, `function_id`, `max_memory_chars`, `max_tokens`, `strict` and `token_threshold` are promoted either way. Other checkpoint keys are not promoted. Behavior options merge in this order: trait options, behavior options, attachment options, phase options. Maps compile in key order; arrays retain declaration order. Checkpoint scheduling merges trait defaults, explicit `agent_options.checkpoint`, then host `config.checkpoint`. Session-wide defaults precede the agent values. Maps merge recursively; lists replace, including empty lists. False, zero and empty strings are explicit overrides. The detached effective checkpoint options override binding defaults and reach both the binding and function fallback. Bindings run first; a strict binding failure prevents fallback. Absent configuration does not enable checkpointing. See [Sessions](./sessions.md#checkpoints) and [Dataflow](./dataflow.md#agent-checkpoints) for scheduling and sizing. Tool wrappers must preserve every original call ID exactly once, even when redirecting tools or reordering calls. Missing, duplicated or added IDs fail validation before execution. ### Static Memory Static memory items are appended to the system prompt: ```yaml - name: assistant kind: registry.entry meta: type: agent.gen1 name: assistant prompt: You are a helpful assistant. model: gpt-4o memory: - "User prefers concise answers" - "Always cite sources when possible" ``` ### Dynamic Memory Contract Configure dynamic memory recall through an external implementation: ```yaml memory_contract: implementation_id: app:memory_store context: user_id: "${user_id}" options: max_items: 3 max_length: 1000 recall_cooldown: 1 min_conversation_length: 2 ``` The memory contract is called during eligible steps to recall relevant background context. Results are sent as positional developer messages and returned in `context_notes` for the host to persist. Recall failures do not stop generation; `memory_recall_error` describes the failure. An empty memory list is not an error. | Option | Default | Description | |--------|---------|-------------| | `max_items` | `3` | Maximum memory items per recall | | `max_length` | `1000` | Maximum total character length | | `recall_cooldown` | `1` | Minimum steps between recalls | | `min_conversation_length` | `2` | Minimum conversation turns before first recall | ## Resolver Contract When `load_agent()` receives a string identifier, it first tries to resolve it through the `wippy.agent:resolver` contract. If no resolver is bound or the resolver returns nil, it falls back to the registry lookup. This allows applications to implement custom agent resolution, such as loading agent definitions from a database. ### Binding a Resolver Define a resolver function and bind it to the contract: ```yaml entries: - name: agent_resolver.resolve kind: function.lua source: file://agent_resolver.lua method: resolve modules: - logger imports: agent_registry: wippy.agent.discovery:registry - name: agent_resolver_binding kind: contract.binding contracts: - contract: wippy.agent:resolver default: true methods: resolve: app:agent_resolver.resolve ``` ### Resolver Implementation The resolver receives `{ agent_id = "..." }` and returns an agent spec table or nil: ```lua local agent_registry = require("agent_registry") local CUSTOM_PREFIX = "custom:" function resolve(args) local agent_id = args.agent_id if not agent_id then return nil, "agent_id is required" end if agent_id:sub(1, #CUSTOM_PREFIX) == CUSTOM_PREFIX then local id = agent_id:sub(#CUSTOM_PREFIX + 1) -- load from database, config file, or any other source return { id = agent_id, name = "custom-agent", prompt = "You are a custom agent.", model = "class:balanced", max_tokens = 1024, tools = {}, } end -- fall back to registry local spec, err = agent_registry.get_by_id(agent_id) if not spec then spec, err = agent_registry.get_by_name(agent_id) end return spec, err end return { resolve = resolve, } ``` ### Resolution Order 1. Try `wippy.agent:resolver` contract (if bound) 2. Try registry lookup by ID 3. Try registry lookup by name 4. Return error if not found Custom resolution can load agent definitions outside the framework registry, including definitions scoped by user or workspace. ## See Also - [LLM](framework/llm.md) — Underlying model interface - [Building an LLM Agent](../tutorials/llm-agent.md) — Build an agent step by step - [Framework Overview](framework/overview.md) — Install and import framework modules ## Navigation Previous: "LLM" (framework/llm) Next: "Sessions" (framework/sessions)