Building a personal AgentField agent
A personal agent is a capability installed on this machine. Once it's running,
the local control plane routes calls to it, other agents and coding assistants
can discover and delegate to it, and the AgentField Desktop app shows it with
its keys and lifecycle controls. The deliverable is not a repository — it is a
working, registered, callable agent.
This skill is the workflow for getting that done. It does not use Docker,
Docker Compose, a new Git repository, or a project CLAUDE.md unless the user
independently asks for one of those.
Before building
Check once whether an installed agent already covers the request: af list
for what's installed, and the control plane's discovery
(GET /api/v1/discovery/capabilities) for what each running agent's reasoners
actually do (the agentfield-use skill documents this surface). If a healthy
installed agent already does the job, say so and offer to use it instead of
building a duplicate — unless the user explicitly asked to build a new or
replacement agent, in which case build it. A stopped-but-capable installation
is not a reason to duplicate either; offer to start it with af run <name>.
For the agent's design, fetch the live SDK docs first —
https://agentfield.ai/llms.txt (and llms-full.txt for depth) — that is the
SDK ground truth. Decompose the job into reasoners the same way the
agentfield skill teaches: by cognitive jobs, not by a single catch-all
prompt. Personal agents are usually small — a handful of reasoners on one node
is normal — but the design bar is the same.
Workflow
Build stable real source. Choose one filesystem-safe kebab-case
package/name/node ID, <name>, and author the agent at
~/agentfield-agents/<name>. This directory is the durable source of truth
the user will edit later. Do not author in a temporary directory, a
disposable checkout, or the generated ~/.agentfield installation copy.
Run language-native syntax checks and tests on the source before
installing.
Package the source. Write the manifest at
~/agentfield-agents/<name>/agentfield-package.yaml. Put
config_version: v1 at the top — the manifest schema version, distinct
from the agent release version. Declare name, release version,
description, author, language, a runnable entrypoint.start that
matches the source and language, entrypoint.healthcheck: /health,
agent_node.node_id equal to <name>, its matching
agent_node.default_port, and only install dependencies the source needs.
config_version: v1
name: pricing-agent
version: 0.1.0
description: Answers pricing questions from the product catalog
author: <user>
language: python
entrypoint:
start: python main.py
healthcheck: /health
agent_node:
node_id: pricing-agent
default_port: 9301
dependencies:
python: [requests]
user_environment:
- name: OPENROUTER_API_KEY
description: LLM provider key used for all reasoning calls
type: secret
scope: global
Declare secrets safely. For every external key the source actually
uses, declare a user_environment entry with name, an actionable
description, type: secret, and an explicit scope. Use scope: global
only for deliberately reusable credentials such as a model-provider key;
use scope: node for credentials or configuration specific to this agent.
Do not declare invented keys.
Install and configure. Run af install ~/agentfield-agents/<name>.
Configure each declared global key with af secrets set KEY and each node
key with af secrets set --node <name> KEY, letting the CLI prompt/stdin
take the value. Never invent, echo, commit, put into
agentfield-package.yaml, or include secret values in a handoff.
Start and verify registration. Run af run <name>, then poll
GET ${AGENTFIELD_SERVER:-http://localhost:8080}/api/v1/nodes until the
node ID is registered in an active/healthy state. An install entry, af list entry, or successful process spawn alone is not success.
Invoke live. Invoke the public entry reasoner through the control plane
with a representative request. For nontrivial work use async execution and
poll (the agentfield-use skill documents the execute/poll surface);
require a terminal successful result before calling the build done.
Handle failures honestly. Diagnose and safely retry correctable
failures from installation, secret setup, startup, registration, or
invocation (af logs <name> is the first stop). If a required secret value
is known only to the user, stop with a blocking handoff that names the
needed key and scope but never its value. Do not claim completion until
healthy registration and a live reasoner result both succeed.
Hand off. Tell the user the agent is installed, running, and now
appears in the AgentField Desktop app, where its declared keys are
presented as a form and its lifecycle has an auto-start toggle. Include:
the stable source path, the manifest path, the installed name, the public
entry reasoner's invocation target, the registration and live-call
verification results, and the commands to restart
(af stop <name> && af run <name>), stop (af stop <name>), inspect logs
(af logs <name>), and update after source edits
(af install ~/agentfield-agents/<name> followed by af run <name>).
1---2name: agentfield-personal3version: 0.1.04description: "Build and install a personal AI agent on this machine's AgentField: real source in ~/agentfield-agents, packaged with agentfield-package.yaml, installed with `af install`, started with `af run`, registered on the local control plane, and visible in AgentField Desktop with a keys form and an auto-start toggle. Use when the user wants an agent that lives on their machine as a persistent capability — a pricing agent, a support agent, a research agent — rather than a deployable project. A standalone repository with Docker Compose is the `agentfield` skill; calling agents that already exist is the `agentfield-use` skill."5metadata:6 source: https://skillmd.com/skills/agent-field/agentfield-personal7---89# Building a personal AgentField agent1011A personal agent is a capability installed on this machine. Once it's running,12the local control plane routes calls to it, other agents and coding assistants13can discover and delegate to it, and the AgentField Desktop app shows it with14its keys and lifecycle controls. The deliverable is not a repository — it is a15working, registered, callable agent.1617This skill is the workflow for getting that done. It does not use Docker,18Docker Compose, a new Git repository, or a project `CLAUDE.md` unless the user19independently asks for one of those.2021## Before building2223Check once whether an installed agent already covers the request: `af list`24for what's installed, and the control plane's discovery25(`GET /api/v1/discovery/capabilities`) for what each running agent's reasoners26actually do (the `agentfield-use` skill documents this surface). If a healthy27installed agent already does the job, say so and offer to use it instead of28building a duplicate — unless the user explicitly asked to build a new or29replacement agent, in which case build it. A stopped-but-capable installation30is not a reason to duplicate either; offer to start it with `af run <name>`.3132For the agent's design, fetch the live SDK docs first —33`https://agentfield.ai/llms.txt` (and `llms-full.txt` for depth) — that is the34SDK ground truth. Decompose the job into reasoners the same way the35`agentfield` skill teaches: by cognitive jobs, not by a single catch-all36prompt. Personal agents are usually small — a handful of reasoners on one node37is normal — but the design bar is the same.3839## Workflow40411. **Build stable real source.** Choose one filesystem-safe kebab-case42 package/name/node ID, `<name>`, and author the agent at43 `~/agentfield-agents/<name>`. This directory is the durable source of truth44 the user will edit later. Do not author in a temporary directory, a45 disposable checkout, or the generated `~/.agentfield` installation copy.46 Run language-native syntax checks and tests on the source before47 installing.48492. **Package the source.** Write the manifest at50 `~/agentfield-agents/<name>/agentfield-package.yaml`. Put51 `config_version: v1` at the top — the manifest schema version, distinct52 from the agent release `version`. Declare `name`, release `version`,53 `description`, `author`, `language`, a runnable `entrypoint.start` that54 matches the source and language, `entrypoint.healthcheck: /health`,55 `agent_node.node_id` equal to `<name>`, its matching56 `agent_node.default_port`, and only install dependencies the source needs.5758 ```yaml59 config_version: v160 name: pricing-agent61 version: 0.1.062 description: Answers pricing questions from the product catalog63 author: <user>64 language: python65 entrypoint:66 start: python main.py67 healthcheck: /health68 agent_node:69 node_id: pricing-agent70 default_port: 930171 dependencies:72 python: [requests]73 user_environment:74 - name: OPENROUTER_API_KEY75 description: LLM provider key used for all reasoning calls76 type: secret77 scope: global78 ```79803. **Declare secrets safely.** For every external key the source actually81 uses, declare a `user_environment` entry with `name`, an actionable82 `description`, `type: secret`, and an explicit scope. Use `scope: global`83 only for deliberately reusable credentials such as a model-provider key;84 use `scope: node` for credentials or configuration specific to this agent.85 Do not declare invented keys.86874. **Install and configure.** Run `af install ~/agentfield-agents/<name>`.88 Configure each declared global key with `af secrets set KEY` and each node89 key with `af secrets set --node <name> KEY`, letting the CLI prompt/stdin90 take the value. Never invent, echo, commit, put into91 `agentfield-package.yaml`, or include secret values in a handoff.92935. **Start and verify registration.** Run `af run <name>`, then poll94 `GET ${AGENTFIELD_SERVER:-http://localhost:8080}/api/v1/nodes` until the95 node ID is registered in an active/healthy state. An install entry, `af96 list` entry, or successful process spawn alone is not success.97986. **Invoke live.** Invoke the public entry reasoner through the control plane99 with a representative request. For nontrivial work use async execution and100 poll (the `agentfield-use` skill documents the execute/poll surface);101 require a terminal successful result before calling the build done.1021037. **Handle failures honestly.** Diagnose and safely retry correctable104 failures from installation, secret setup, startup, registration, or105 invocation (`af logs <name>` is the first stop). If a required secret value106 is known only to the user, stop with a blocking handoff that names the107 needed key and scope but never its value. Do not claim completion until108 healthy registration and a live reasoner result both succeed.1091108. **Hand off.** Tell the user the agent is installed, running, and now111 appears in the AgentField Desktop app, where its declared keys are112 presented as a form and its lifecycle has an auto-start toggle. Include:113 the stable source path, the manifest path, the installed name, the public114 entry reasoner's invocation target, the registration and live-call115 verification results, and the commands to restart116 (`af stop <name> && af run <name>`), stop (`af stop <name>`), inspect logs117 (`af logs <name>`), and update after source edits118 (`af install ~/agentfield-agents/<name>` followed by `af run <name>`).