Agent Definition

How it works in practice

A team configures an agent definition called Release🚢ReleaseProduct SpecificationA shipped version of the productView reference → Notes Drafter. Its specification names the model, grants three skills (read the merged pull requests, query the changelog🕰️ChangelogProduct SpecificationA record of changes shipped in a releaseView reference →, post a draft to the docs repo), and sets a permission boundary: read-only on code, write-only to a single draft branch. The definition itself does no work. When a tagged release lands, the agent definition runs an agent session🧑‍💻Agent SessionWorkflows & AgentsAn agent working sessionView reference → that reads the diff, drafts the notes, and opens a draft pull request. The same template can run a hundred times across a hundred releases, and each run is traceable back to the one specification that produced it.

Agent definition vs. its neighbours

• Agent session is a single execution of the definition, with its own context and transcript. The definition is the recipe; the session is one meal cooked from it. A definition has no transcript; a session always does.
• Agent skill🪄Agent SkillWorkflows & AgentsA capability of an agentView reference → is one capability💪CapabilityStrategyAn ability that enables value deliveryView reference → the definition is permitted to invoke. A definition references many skills; a skill exists independently and can belong to several definitions.
• Agent hook🧷Agent HookWorkflows & AgentsA trigger connecting an agent to an eventView reference → is the event trigger that decides when a definition runs. The definition says what the agent is; the hook says when it wakes.

In the graph

In the Unified Product Graph, an agent definition sits in the automation region as the hub of the agent primitives. A product owns its agents through product_assisted_by_agent_definitionProductassisted byAgent Definitionhierarchy. From the definition, three edges fan out: agent_definition_runs_agent_sessionAgent DefinitionrunsAgent Sessionhierarchy records each execution, agent_definition_capable_of_agent_skillAgent Definitioncapable ofAgent Skillhierarchy declares its capabilities, and agent_definition_triggered_via_agent_hookAgent Definitiontriggered viaAgent Hookhierarchy wires it to its triggers. It can also agent_definition_spawns_agent_taskAgent DefinitionspawnsAgent Taskhierarchy to assign discrete work. Keeping the definition distinct from its sessions means the specification stays auditable while the runs accumulate underneath it, so a question like "what is this agent allowed to do, and what has it actually done?" has two clean answers.