Give the agent clear capabilities

Instructions describe the job, skills provide procedures, and tools expose operations. Review all three before connecting an agent to real data.

Available

Explore the YAML reference and sample files →

Know the agent folder#

customer-care/
  application.yaml
  refund-helper/
    agent.yaml
    skills/
      refunds/
        SKILL.md
    tools.py

agent.yaml declares the agent and its configuration. Skills live in named folders. Python tools use the @tool decorator, typed arguments, and docstrings to describe their contract. Run helixor agent check customer-care after edits; fix reported file and line errors before testing.

Keep instructions specific: what information to ask for, when to use each skill, and when to ask a person. Put enforced business restrictions on governed tools in rules.

Declare how tools may run#

Tool declarations
Declaration	Meaning
`reads: true`	A read-only operation eligible for draft tests and rule context. Its implementation must actually be read-only.
`governed: true`	A tool checked by the decision engine before execution. Configure its rules and required context.
`approval: manager`	The declared approval role for the tool’s held-call path; it is not an approval already granted.

The product server executes tools through the execution pool. The local CLI service has different execution options and fewer platform features. Check the environment before using tools with effects.

Edit Python tools from a browser draft#

Set HELIXOR_AGENT_URL to the product agent-service URL and configure HELIXOR_AGENT_ADMIN_TOKEN with your owner token. Pull the application into a new or empty directory before changing it. For an open draft:

helixor agent pull customer-care --draft
# Edit customer-care/refund-helper/tools.py in your code editor.
helixor agent check customer-care
helixor agent push --draft customer-care

To begin from live, use helixor agent pull customer-care without --draft. Open the resulting draft in Build and review it before deployment. Keep the pull metadata with the folder; it is used to detect concurrent changes.

Keep small working state#

Code tools that need data across calls can declare a state scope in agent.yaml:

runtime:
  state: conversation

conversation keeps separate state for each conversation; agent shares it across the agent’s conversations in the tenant. The default is none. Tools use helixor_agent.state_dir() for small files, with a total limit of 256 KiB. The service stores this working data and checks revisions when saving it.

Read-only calls, draft tests, and rule dry runs do not save changes to state. Failed calls do not save changes either. Use a business system of record for authoritative records.

If you see AGENT_STATE_NOT_KEPT: the tool ran but its updated state could not be stored. Do not repeat the effect. Investigate the actual outcome first.

Let agents message each other#

Creating two agents in one application does not by itself authorize messaging. Declare the recipient under the sender’s agents, name the sender in the recipient’s accept_from, and add the matching from, to, and why entry under the application’s messaging. Check the application as a whole to catch mismatches.