Mirrors/talemate
1
0
Fork 0
mirror of https://github.com/vegu-ai/talemate.git synced 2026-09-02 20:20:40 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
talemate/docs/user-guide/node-editor/reference/nodes/agents.md

319 lines
11 KiB
Markdown
Raw Permalink Normal View History

0.39.0 (#274) - **Help Agent** — A new agent that answers questions about Talemate itself — settings, agents, clients, the world editor — grounded in the bundled documentation, and able to change agent and application settings on request. - **Timeline Rollback** — Scrub a slider across a scene's automatic version history, preview the message history at any revision, then roll the scene back in place or fork the revision into a new save. - **Pi Bridge Client** — A new client type that drives generations through the pi coding agent's headless RPC mode, making any model pi can reach usable in Talemate. - **Application Settings** — Settings move out of their modal into an always-available Settings tab, with a single topic-grouped sidebar, a settings search, all API keys on one page, and unsaved-change tracking. - **Scene Library** — The home screen is rebuilt as a full-page landing view with a file-tree scene library, cover thumbnails and per-save metadata, scene and save deletion, and a drag-and-drop import dropzone. - **Fast Character Creation** — Generate a character in a single request instead of one prompt per aspect, with a Consolidate multi-select, a token budget, and a Fill in misses pass. Off by default. - **Scene Backdrop** — Set any scene illustration as a backdrop filling the scene view behind the messages, saved with the scene, with configurable text legibility and an Immersive quick-toggle. - **Scene Visual Manager** — World Editor → Scene gains a Visuals tab to browse, upload, generate and delete the scene's backgrounds and illustrations, and set the cover image and backdrop. - **Visual Prompt Finalization** — Post-processing actions — match and replace, or a free-form AI instruction — rewrite image prompts right before they reach the image backend, with per-scene and per-character overrides and reusable template sets. - fixes #271 - fixes #275 Plus 25 improvements and 39 bug fixes — see [CHANGELOG.md](https://github.com/vegu-ai/talemate/blob/prep-0.39.0/CHANGELOG.md#0390) for the full list.
2026-08-29 13:21:22 +03:00
# Agent Nodes
Generic agent interaction available for every agent: fetch an agent instance, call agent functions (optionally conditionally), and read or count agent state variables.
<!-- glossary:generated - everything below this line is generated by `python -m talemate.game.engine.nodes.tools glossary --write` - do not edit -->
_9 nodes._
| Node | Registry path |
| --- | --- |
| [Call Agent Function](#call-agent-function) | `agents/CallAgentFunction` |
| [Call Agent Function (Conditional)](#call-agent-function-conditional) | `agents/CallAgentFunctionConditional` |
| [Counter Agent State](#counter-agent-state) | `agents/CounterAgentState` |
| [Dynamic Instruction](#dynamic-instruction) | `agents/DynamicInstruction` |
| [Get Agent](#get-agent) | `agents/GetAgent` |
| [Get Agent State](#get-agent-state) | `agents/GetAgentState` |
| [Set Agent State](#set-agent-state) | `agents/SetAgentState` |
| [Toggle Agent Action](#toggle-agent-action) | `agents/ToggleAgentAction` |
| [Unset Agent State](#unset-agent-state) | `agents/UnsetAgentState` |
## Call Agent Function
`agents/CallAgentFunction`
Call a function on an agent and return its result.
The agent can be given as an agent instance or by name. The function is
looked up on the agent by name and called with the given arguments as
keyword arguments (coroutine functions are awaited).
**Inputs**
| Input | Type | Description |
| --- | --- | --- |
| `agent` | `str,agent` | The agent (instance or name) to call the function on |
| `function_name` | `str` | The name of the function to call on the agent |
| `arguments` | `dict` | Dict of keyword arguments to pass to the function |
**Outputs**
| Output | Type | Description |
| --- | --- | --- |
| `result` | `any` | The return value of the function call |
**Properties**
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `agent` | `str` | `""` | The agent to call the function on. Choices are generated at runtime. |
| `function_name` | `str` | `""` | The name of the function to call on the agent |
| `arguments` | `dict` | `{}` | The arguments to pass to the function |
## Call Agent Function (Conditional)
`agents/CallAgentFunctionConditional`
Call a function on an agent and return its result.
Provides a required `state` input causing the node to only run when a state is provided
**Inputs**
| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `agent` | `str,agent` | The agent (instance or name) to call the function on |
| `function_name` | `str` | The name of the function to call on the agent |
| `arguments` | `dict` | Dict of keyword arguments to pass to the function |
**Outputs**
| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `result` | `any` | The return value of the function call |
**Properties**
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `agent` | `str` | `""` | The agent to call the function on. Choices are generated at runtime. |
| `function_name` | `str` | `""` | The name of the function to call on the agent |
| `arguments` | `dict` | `{}` | The arguments to pass to the function |
## Counter Agent State
`agents/CounterAgentState`
Increment a numeric variable in an agent's state and return the new value.
Provides a required `state` input causing the node to only run when a state is provided
**Inputs**
| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `name` | `str` | (optional) The name of the counter variable |
| `reset` | `bool` | If true, the value will be reset to 0 (optional) |
| `reset_cap` | `number` | If set, the counter resets to 0 once it reaches this value (optional) |
| `agent` | `str,agent` | The agent (instance or name) whose state holds the counter |
**Outputs**
| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `name` | `str` | The name that was used |
| `value` | `any` | The new value |
| `scope` | `str` | The scope that was used |
| `reset_cap` | `number` | The reset cap that was used |
| `reset` | `bool` | Whether the counter was reset |
| `new_cycle` | `bool` | True if the counter was at 0 before this run |
**Properties**
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `scene`, `context`. |
| `increment` | `int` | `1` | increment |
| `reset` | `bool` | `False` | reset |
| `reset_cap` | `int` | `0` | reset_cap |
| `agent` | `str` | `unset` | The agent to manipulate the state on. Choices are generated at runtime. |
## Dynamic Instruction
`agents/DynamicInstruction`
Create a dynamic instruction object to use for instruction injection
in event handlers.
A header is required at runtime (raises an error if missing). List content
is joined with newlines.
**Inputs**
| Input | Type | Description |
| --- | --- | --- |
| `header` | `str` | (optional) The header (title) of the dynamic instruction |
| `content` | `str,list` | (optional) The content of the dynamic instruction (string or list of strings) |
**Outputs**
| Output | Type | Description |
| --- | --- | --- |
| `dynamic_instruction` | `dynamic_instruction` | The dynamic instruction object |
**Properties**
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `header` | `str` | `unset` | The header of the dynamic instruction |
| `content` | `text` | `unset` | The content of the dynamic instruction |
## Get Agent
`agents/GetAgent`
Get an agent instance by name.
Does nothing if no agent name is set; raises an error if the agent cannot
be found.
**Outputs**
| Output | Type | Description |
| --- | --- | --- |
| `agent` | `agent` | The agent instance |
**Properties**
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `agent_name` | `str` | `""` | The name of the agent to get. Choices are generated at runtime. |
## Get Agent State
`agents/GetAgentState`
Get a variable from an agent's state.
The `scene` scope reads agent state stored with the scene, the `context`
scope reads the agent's context state.
**Inputs**
| Input | Type | Description |
| --- | --- | --- |
| `name` | `str` | (optional) the name of the variable to get |
| `default` | `any` | value to return if the variable is not set (optional) |
| `agent` | `str,agent` | the agent (instance or name) to read the state from |
**Outputs**
| Output | Type | Description |
| --- | --- | --- |
| `name` | `str` | the name that was retrieved |
| `value` | `any` | the value that was retrieved |
| `scope` | `str` | the scope that was retrieved |
**Properties**
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `scene`, `context`. |
| `agent` | `str` | `unset` | The agent to manipulate the state on. Choices are generated at runtime. |
## Set Agent State
`agents/SetAgentState`
Set a variable in an agent's state.
The `scene` scope writes agent state stored with the scene, the `context`
scope writes to the agent's context state.
Provides a required `state` input causing the node to only run when a state is provided
**Inputs**
| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `name` | `str` | (optional) the name of the variable to set |
| `value` | `any` | the value to set |
| `agent` | `str,agent` | the agent (instance or name) to set the state on |
**Outputs**
| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `name` | `str` | the name that was set |
| `value` | `any` | the value that was set |
| `scope` | `str` | the scope that was used |
**Properties**
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `scene`, `context`. |
| `agent` | `str` | `unset` | The agent to manipulate the state on. Choices are generated at runtime. |
## Toggle Agent Action
`agents/ToggleAgentAction`
Allows disabling or enabling an agent action that can be disabled
Raises an error if the agent or the action cannot be found, or if the
action is one that cannot be disabled — those are always enabled and
are not togglable from a graph.
**Inputs**
| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `agent` | `str,agent` | (optional) The agent (instance or name) to toggle the action on |
| `action_name` | `str` | (optional) The name of the action to toggle |
| `enabled` | `bool` | (optional) Whether to enable or disable the action |
**Outputs**
| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `agent` | `agent` | The resolved agent instance |
| `action_name` | `str` | The action name, passed through |
| `enabled` | `bool` | The action's effective enabled state after the write — when a scene override is active it takes the write, so this reflects the override rather than the agent's global setting |
**Properties**
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `agent` | `str` | `""` | The agent to toggle the action on. Choices are generated at runtime. |
| `action_name` | `str` | `""` | The name of the action to toggle |
| `enabled` | `bool` | `True` | Whether to enable or disable the action |
## Unset Agent State
`agents/UnsetAgentState`
Unset a variable in an agent's state.
The `scene` scope removes agent state stored with the scene, the `context`
scope removes from the agent's context state.
Provides a required `state` input causing the node to only run when a state is provided
**Inputs**
| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `name` | `str` | (optional) the name of the variable to unset |
| `agent` | `str,agent` | the agent (instance or name) to unset the state on |
**Outputs**
| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `name` | `str` | the name that was unset |
| `value` | `any` | the value that was unset |
| `scope` | `str` | the scope that was used |
**Properties**
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `str` | `unset` | The name of the variable to manipulate |
| `scope` | `str` | `"local"` | Which scope to manipulate. Choices: `scene`, `context`. |
| `agent` | `str` | `unset` | The agent to manipulate the state on. Choices are generated at runtime. |
Reference in New Issue Copy Permalink