Write your first manifest

In step 1 you started the runtime and installed the CLI. Now you describe your first agent in a single file— the manifest. Everything the runtime needs to know about this agent lives here until you are ready to hand the file over.

Scaffold agent.yaml

phrony init creates a starter file in your project. You will turn it into a complete description (OpenAI plus a declared secret) like the example below. The command only writes local files—it does not talk to the runtime. See phrony init for details.

$ phrony init ./my-agent

On success you get created ./my-agent/agent.yaml. The command fails if agent.yaml already exists in that directory.

Example manifest

Here is the full picture. The sections below explain each block; use this as your target when editing the file from phrony init.

apiVersion: phrony.com/v1
kind: Agent

metadata:
  name: my-agent
  namespace: default
  version: 0.1.0

secrets:
  openai:
    fromEnv: OPENAI_API_KEY

spec:
  purpose: Answer questions clearly and concisely.
  instructions:
    text: |
      You are a helpful assistant. Be accurate and concise.
  model:
    provider: openai
    name: gpt-4o

output:
  format: text

What each section does

Read the file from top to bottom. Each block answers one question about your agent.

apiVersion and kind

What kind of document is this? phrony.com/v1 and Agent say “this YAML follows the Phrony agent shape.” Every field below is interpreted in that context.

apiVersion: phrony.com/v1
kind: Agent

metadata

Who is this agent? namespace and name are its address (here, default/my-agent). version labels this revision—when you change the file later, bump the version so you can tell iterations apart.

metadata:
  name: my-agent
  namespace: default
  version: 0.1.0

secrets

What credentials will this agent need? Do not put API keys in the file. This block is a placeholder: it says that when you run this agent later, you will need an openai credential supplied as OPENAI_API_KEY. Name it openai to match spec.model.provider below. Step 3 shows how to pass that secret to the runtime.

secrets:
  openai:
    fromEnv: OPENAI_API_KEY

spec.purpose

Why does this agent exist? A one-line summary for humans reading the repo. It is not the prompt the model sees on each turn.

spec:
  purpose: Answer questions clearly and concisely.

spec.instructions

How should the model behave? This is the system prompt—what the model is told every time. Inline text is enough to start; when the prompt grows you can move it to a separate file and reference it with ref.

spec:
  instructions:
    text: |
      You are a helpful assistant. Be accurate and concise.

spec.model

Which model answers? provider: openai and name: gpt-4o pick OpenAI’s API and model id. This agent will use the openai secret you named above.

spec:
  model:
    provider: openai
    name: gpt-4o

output

What do you get back? format: text means plain assistant replies—enough for a first chat. JSON shapes come later when you need structured answers.

output:
  format: text

Check the file

Run a local sanity check on the manifest you wrote—you do not need your API key in the shell yet:

$ phrony agents validate ./my-agent/agent.yaml

Fix anything the command reports. In the next step you will send this file to the runtime and talk to your agent. See phrony agents validate for details.