A friendly robot

Home | Docs for Humans | Policies for Teams | GitHub

AGENTS.talk Reference

Every line that AGENTS.talk can hold. For a guided tour, read Your AGENTS.talk. For rules across an organization, read Policies for Teams.

Top Lines

At the top of AGENTS.talk: what scripts and programs can reach, and how the session is recorded.

allow

allow env <NAME>, ... | allow changes to <path>, ... | allow fetch from '<host>' or <url pattern>, ... | allow secret <NAME> for fetch to '<host>' or <url pattern>, ... | allow secret <NAME> for run | allow secret <NAME> for subagents | use model '<id>' for subagents [with secret <NAME>] | use model '<id>' for judging [with secret <NAME>]

Examples

allow env PATH, HOME
allow changes to @/.github/, @/.gitignore
allow fetch from http://localhost:5173/
allow secret GITHUB_TOKEN for fetch to https://api.github.com/repos/bigskysoftware/

limit

limit output keeping the first <n> lines | the last <n> lines | the first <n> and the last <n> lines | lines matching pattern /x/ [or <n> KB]

Choose the print output that the agent sees from one script, with the same forms as run ... keeping. Only at the top of AGENTS.talk, or in a policy. One line takes the place of the cut lines, and the previous output has all of them. AGENTS.talk cuts first, then the policy, then the host (1000 lines or 30 KB).

Examples

limit output keeping the first 200 and the last 200 lines
limit output keeping the last 400 lines or 20 KB

audit

the audit | audit as json (in AGENTS.talk) | keep audit for <n> days (in AGENTS.talk)

Examples

for step in the audit
  if step's kind is 'write'
    print step's target
  end
end

taint

taint on | taint off | taint required | taint asks before <push, secrets, commit, network runs, new hosts | nothing> | keep untrusted inputs up to <n> MB | let the judge approve clean inputs | judge untrusted inputs automatically | judge with prompt '<text>'

Examples

taint required
taint asks before push, secrets, commit
keep untrusted inputs up to 5 MB
use model 'claude-haiku-5-5' for judging with secret ANTHROPIC_API_KEY
allow secret ANTHROPIC_API_KEY for subagents
judge untrusted inputs automatically

Tools

What your agent can run.

tool

[untrusted] tool <name> [with <param>, ...] ... end

Examples

# Runs one test class.
tool run_test with name
  run 'mvn' with 'test', '-Dtest=' + name
end
# Shows a GitHub issue.
untrusted tool issue with id
  run 'gh' with 'issue', 'view', id
end

run

run <program and args> | run <program> with <arg>, ... [using secret <NAME>, ...] [in a sandbox [with network, local network, writes to <path>, reads of <path>]] [within <duration>] [keeping the first <n> lines | the last <n> lines | the first <n> and the last <n> lines | lines matching pattern /x/]

Examples

tool test
  run 'npm test' in a sandbox within 10 minutes keeping the last 200 lines
end
tool lint
  run 'npx eslint .' in a sandbox keeping lines matching pattern /error/
end
tool install
  run 'npm install' in a sandbox with network, writes to '~/.npm'
end
tool publish
  run 'npm publish' using secret NPM_TOKEN
end
# Summarizes the most important open issues.
tool summarize_issues
  run 'Summarize the most important open issues' in a subagent with only gh_issues
end

start

start <program> [with <arg>, ...] as <name> [using secret <NAME>, ...] [in a sandbox [with ...]] | start <prompt> as <name> in a subagent with only <tool>, ...

Examples

tool site_server
  start 'npm run serve-site' as 'site' in a sandbox
end

process

process <name> | the processes

A background process that a tool started: name, status (running, exited or stopped), code, and output (the last 64 KB). 'of' also works: the output of process 'site'. 'the processes' lists them, newest first.

Examples

print the output of process 'site'
if the status of process 'site' is 'running'
  stop process 'site'
end
print the processes

import

import <path to a .talk file>

Load the tools from another .talk file. Only in AGENTS.talk and the files that it imports. ./ starts from the importing file, @/ from the project root.

Examples

import ./talk/git.talk
import @/talk/maven.talk

Hooks

Your rules, before and after each step.

before

before <step> ... end

Examples

before change
  if the change's path ends with '.env'
    reject 'Cannot change env files!'
  end
end

after

after <step> ... end

Run commands after a step. Only in AGENTS.talk. 'the ' holds the step, and 'the result' holds what it gave back.

Examples

after run
  print 'ran ' + the run's program + ': ' + the result's code
end

reject

reject <message>

In a 'before' hook: stop the step. In a tool: stop the tool. The script gets an error with the message, at the command that it stopped. 'on error' can catch it.

Examples

before write
  reject 'This project is read only'
end
tool deploy with target
  if target is 'prod'
    reject 'Only a human deploys to prod'
  end
  run 'fly' with 'deploy', '--app', 'shop-' + target in a sandbox with network
end

ask

ask <question> [with <choice> or <choice>] [within <duration>]

Examples

ask 'Which branch should I use?'
print it
ask 'Delete the old logs?' with 'yes' or 'no' within 5 minutes
if the result is 'yes'
  print 'ok'
end

Hook Steps

In a hook, the <step> holds the step, such as the run's args. the session is untrusted is true after web text that the human did not approve. For run and start, sandbox is null, or { network, reads, writes }.

Step Fields
read path, and text in an after hook
write, append kind, path, text
replace kind, path, old, new; for replace lines: from, to, text
put kind, path, line, where, text
remove kind, path, from, to
move kind, path, to
delete kind, path
change any file change above, with its kind
undo kind, path, text
run program, args, sandbox, secrets
start program, args, name, sandbox, secrets
stop name
git operation, args; files and message for commit; branch for switch, merge and rebase
fetch url, method, secrets, and status in an after hook
a tool name args, named