Create and configure an agent

The repository provides agent and tool contracts, but it does not verify a complete general-purpose agent builder or stable button labels. This guide therefore treats configuration as a reviewable contract rather than a click-by-click UI walkthrough.

Creation labels, model controls, instruction fields, and test controls require direct UI verification.

Because a universal builder is not verified, configuration guidance should be expressed as a contract that another implementation can satisfy. The contract identifies the agent slug and purpose, model dependency, instructions, tool set, permissions, credentials, approval boundaries, expected evidence, and evaluation input. A test run then shows whether those declarations result in valid actions and transitions. Missing UI controls should remain a review gap rather than being replaced with imagined field names or click sequences.

Prerequisites

Before configuration begins, confirm that the registry entry and implementation status can support execution. A planned or not-started agent is not a valid test target.

Before a definition is shared, record which parts are executable and which are descriptive. A complete contract can still rely on planned tools, stub connectors, or demo fixtures. Those dependencies should be visible in review notes so another operator does not mistake configuration completeness for runtime readiness.

A contract-oriented setup requires a registry entry, an implementation state other than not_started, an allowed workspace context, a model or route suitable for the definition, and tool contracts that match the intended work. Persistence mode should also be known because it affects which records survive an environment change.

A universal agent builder and its exact form labels are not verified. Use the current registry and configuration contracts as the authoritative fields rather than describing a drag-and-drop or no-code flow.

Identify an existing registry entry or approved configuration path and confirm that its implementation is active or otherwise runnable.

Determine the intended workspace scope, permission mode, tools, credentials, and approval boundaries.

Confirm that the current persistence mode is acceptable for the task.

Prerequisites include a known registry context, an implementation that is not not_started, an eligible model path, and any tools and credentials required by the intended actions. A missing dependency should be resolved before a test run is created.

A run references an agent by slug, and run creation rejects an unknown registry entry. Functional contracts can include workflow steps, evidence, artifacts, proposed actions, approval boundaries, fixtures, and evaluation cases.

the product boundary contract includes the fact that an entry whose implementation is not started cannot create a run. Tool definitions can restrict allowed agents and workspace archetypes.

Demo fixtures and mock contracts must remain labeled as nonproduction evidence.

Create an agent

Record the intended owner and review boundary in surrounding project governance, but do not invent runtime role fields that are absent from the supplied contract. The verified definition fields and status values should remain the documentation source of truth.

Define a stable slug and registry lifecycle separately from implementation status. A definition can be draft or published while the implementation remains stub; that combination should not be advertised as runnable. Functional-agent contracts may include workflow steps, evidence, artifacts, proposed actions, approval boundaries, fixtures, and evaluation cases.

Demo fixtures are useful for testing but must remain clearly identified. They do not prove live connectors, credentials, or external side effects.

A registry definition needs a stable slug and lifecycle and implementation states.

Creation should not imply activation when the implementation remains not_started or stub.

Do not copy demo fixtures into production documentation as if they were live records.

Create the definition around a narrow responsibility and stable slug. The source contracts support registry metadata and functional fixtures, but they do not establish all visual-builder controls or a generally available agent-creation workflow.

Published registry status does not make a stub implementation runnable, and an active implementation does not guarantee every run succeeds.

Choose a model

The agent definition can reference model behavior through the surrounding platform, but this source pack does not define a universal model picker for agent creation. Select a model only through a verified project route and keep catalog presence separate from runtime readiness.

Model choice should be evaluated with the same execution boundaries used elsewhere: provider configuration, credentials, policy, modality, and project availability. Do not hardcode a provider guarantee into the agent definition when routing is intended to remain flexible.

The agent contract can refer to model configuration, but this source pack does not verify a universal model-picker UI.

Select only a model that the relevant Gateway or runtime can actually execute.

Keep model choice separate from tool authority and approval policy.

Model choice should be represented as configuration, not as a guarantee that the model is runnable in every environment. Gateway status, provider credentials, policy, and modality still determine execution readiness.

An entry whose implementation is not started cannot create a run.

Permission mode, risk, execution state, credentials, and approval requirements must be evaluated together.

Model choice belongs in the agent contract, but the source bundle does not prove a universal model picker or automatic fallback configuration for every agent. Keep the selected model, any routing policy, and the agent’s tool permissions as separate concerns so changing a model does not silently widen authority.

Add instructions

Instructions should describe the task boundary and expected result without granting authority that belongs to tool policy. Permission mode, workspace scope, risk level, credential availability, and approval requirements remain independent controls. An instruction that says “send” or “delete” cannot turn a contract-only tool into an available one, bypass an approval gate, or activate an implementation marked not started.

Keep evaluation fixtures separate from live instructions so test-only values are not carried into real runs.

Instructions should state the task, allowed actions, expected outputs, evidence requirements, and conditions that require user input or approval. They should not grant authority that the tool contract denies. A prompt cannot convert a blocked tool into an available one, widen an allow-list, or remove a confirm_every_time requirement.

Keep instructions separate from credentials. Secrets belong in the verified credential path, not in natural-language instructions, fixture data, or general run input.

Instructions should define the task, expected output, boundaries, and evidence needs without granting authority the runtime does not possess.

Avoid embedding secrets or unverified connector details in instruction text.

A model instruction cannot override tool execution state, permission mode, or approval requirements.

Instructions should define purpose, constraints, expected outputs, and where human input or approval is required. Keep them separate from secrets and from tool permissions, which are enforced through their own contracts.

For the initial test, define the smallest contract that can be verified, keep side-effecting tools unavailable until permissions and approvals are explicit, and test through a narrow run.

A contract-oriented guide can identify required fields without inventing a universal builder or control sequence.

Configuration should state model dependency, instructions, tools, permissions, credentials, approvals, evidence, and evaluation input.

Add tools

For each tool, inspect execution state, permission mode, risk level, approval requirement, provider, allowed agents, workspace archetypes, input summary, and output summary. available indicates a current execution path; contract_only and planned do not. Risk and permission also remain independent: a tool can be read-only in one configuration and still unavailable.

The smallest sufficient permission mode is preferable. Use plan_only when execution is not needed, read_only for observation, safe_edit for constrained changes, and full_access only where the contract and approval policy support it.

Choose tools whose execution state is available and whose allowed agent and workspace scope includes the configuration.

Review risk level, read-only status, provider, input and output summaries, and approval requirement.

Contract-only and planned tools belong in design discussion, not an executable tool set.

Add tools only after checking execution state, allowed agents and workspaces, provider, risk, read-only status, permission mode, credentials, and approval requirement. Planned and contract-only tools must remain non-executable in the documentation.

Availability can still be narrowed by the selected agent, workspace, credentials, policy, or approval state.

High-risk or approval-required actions should produce a proposal before any execution authority is assumed.

Tool output should remain tied to its action and evidence records rather than being treated as an unqualified final result.

Adding a tool means binding the agent to a declared contract, not selecting a name from the ToolId union. Confirm execution state, permission mode, risk, approval requirement, provider, allowed agents, workspace scope, and the input and output summaries. Tests that claim live execution must exclude tools whose execution state is planned or contract_only.

Test and review

A test should also verify negative paths. Use a contract-only tool and confirm that it does not execute; use an approval-gated available tool and confirm that the run waits with proposal context; attempt an invalid state transition and confirm that the state machine rejects it. These checks demonstrate that governance boundaries work, not merely that a happy-path fixture can complete.

Document the persistence mode with every test result. A run that appears after a local-file fallback does not prove the durable database path is configured.

Create a narrow manual run with nonsecret input and inspect its state transitions, actions, evidence, output, audit events, and persistence mode. If a tool requires approval, verify that a proposal is created and that the signed agent-run decision changes the action and run as expected. Do not use scaffolded general Approvals cards as proof of persistence.

A successful fixture or demo run should remain labeled as such. Before broader use, confirm that the registry entry is active, tools are available, credentials are configured, and the current environment provides the required persistence.

Create a bounded run with non-destructive inputs and inspect state, actions, evidence, approvals, output, and persistence.

A successful demo fixture does not prove the same behavior in the connected environment.

Keep the page in draft until the actual creation interface and labels are inspected.

Test with one small input and preserve run, action, proposal, evidence, and persistence records. Demo fixtures can help review a contract, but they should be labeled as fixtures rather than evidence of production execution.

An entry marked not started cannot create a run.

The helper and type layers do not prove a universal agent-builder UI, exact form labels, or that every registry field can be edited through the product.

A contract-oriented test should exercise the smallest meaningful path. Confirm that the registry entry exists and that implementation is not not_started; provide only the inputs declared by the agent; select tools whose execution state and scope permit the action; and observe whether the helper allows execution, creates an approval proposal, or blocks the action. A fixture can illustrate expected behavior, but it must remain labeled as a fixture or demo.

Review the resulting run through its state, ordered actions, proposals, decisions, evidence, output, audit events, and persistence mode. This source bundle does not verify a universal visual builder, drag-and-drop step editor, or complete create-agent form, so exact UI labels and button sequences remain outside the page. Configuration guidance should describe the verified contract fields and control boundaries rather than inventing controls that may not exist.