agent

The agent block defines the agent's identity, graph, model, prompt, and capabilities.

The agent block is where you define the agent itself: its name, graph, model, system prompt, and what it is allowed to do. A manifest contains one agent block.

agent.acl

agent "my_agent" {
  graph {
    type = "react"
  }

  version     = "1.0.0"
  description = "A helpful assistant."

  prompt = "You are a helpful assistant. Your name is {{ agent_name }}."

  capabilities      = ["math", "filesystem"]
  capability_policy = "locked"

  model {
    provider = "anthropic"
    name     = "claude-haiku-4-5"
  }
}

Fields

Field	Type	Required	runtime()	Default	Description
`graph`	Graph	yes		…	Execution graph that controls how the agent processes a run.
`version`	string	no	no	`"0.1.0"`	Semver version string embedded in the binary.
`description`	string	no	no	unset	Human-readable description of the agent.
`prompt`	string \| array<PromptMessage> \| LangfusePromptSource	no	no	unset	Prompt messages or source used to guide the agent during a run.
`capabilities`	array<string>	no	yes	unset	Capability tags the agent is allowed to use.
`capability_policy`	string	no	yes	unset	Policy controlling tool access through capability tags.
`model`	AgentModel	yes		…	Default provider and model used for the agent's model calls.

Graph

The graph block selects the implementation that drives the agent. See the graph reference for its behavior.

Field	Type	Required	runtime()	Default	Description
`type`	`react`	yes	no	…	Execution graph used for the agent's runs.
`model`	GraphModelCallPolicy	no		unset	Default timeout and retry settings for model calls.

GraphModelCallPolicy

Field	Type	Required	runtime()	Default	Description
`timeout`	integer	no	yes	unset	Time in milliseconds allowed to establish a model response stream.
`retry`	RetryPolicy	no		unset	Attempts and delays for temporary failures while establishing a model response stream.

RetryPolicy

Field	Type	Required	runtime()	Default	Description
`max_attempts`	integer	yes	yes	…	Maximum attempts, including the first.
`initial_backoff`	integer	yes	yes	…	First retry delay in milliseconds.
`max_backoff`	integer	yes	yes	…	Maximum base delay in milliseconds.

graph {
  type = "react"
}

See ReAct for the graph's behavior.

prompt

The prompt field sets the agent's prompt. It accepts a plain string, a list of role/content objects for multi-turn prompts, or a configured prompt source.

# Plain string
prompt = "You are a helpful assistant."

# Multi-turn
prompt = [
  { role = "system", content = "You are a helpful assistant." },
  { role = "user",   content = "Always be concise." }
]

The prompt supports Jinja2 template syntax. Variables are injected at runtime before each run. The set of available variables is graph-dependent; see ReAct prompt templates for the list the ReAct graph provides, and Write templated prompts for how to use them.

PromptMessage

Field	Type	Required	runtime()	Default	Description
`role`	`system` \| `user` \| `assistant`	yes	no	…	Role assigned to this message as system instructions, a user turn, or an assistant turn.
`content`	string	yes	no	…	Text template rendered as the message content for each run.

LangfusePromptSource

Use a Langfuse source object to retrieve the prompt from Langfuse Prompt Management at runtime:

prompt = {
  source = "langfuse"

  prompt_name = "support/assistant"
  public_key  = runtime("LANGFUSE_PUBLIC_KEY")
  secret_key  = secret(runtime("LANGFUSE_SECRET_KEY"))

  label                 = runtime("LANGFUSE_PROMPT_LABEL", "staging")
  cache_ttl_seconds     = runtime("LANGFUSE_CACHE_TTL_SECONDS", 60)
  fetch_timeout_seconds = runtime("LANGFUSE_FETCH_TIMEOUT_SECONDS", 5)
  max_retries           = runtime("LANGFUSE_MAX_RETRIES", 2)
}

Field	Type	Required	runtime()	Default	Description
`source`	`langfuse`	yes	no	…	Service that supplies the prompt at runtime.
`prompt_name`	string	yes	yes	…	Langfuse prompt name, including any folder path.
`public_key`	string	yes	yes	…	Langfuse project public key.
`secret_key`	string	yes	yes	…	Langfuse project secret key. Normally wrapped in `secret(runtime(...))`.
`base_url`	string	no	yes	`https://cloud.langfuse.com`	Langfuse Cloud or self-hosted base URL.
`label`	string	no	yes	unset	Movable label used to select a prompt version.
`version`	integer	no	yes	unset	Immutable numeric prompt version.
`cache_ttl_seconds`	integer	no	yes	`60`	Local cache lifetime. Set to `0` to disable caching.
`fetch_timeout_seconds`	integer	no	yes	`5`	Fetch timeout for each request attempt.
`max_retries`	integer	no	yes	`2`	Additional attempts for transient fetch failures.

label and version are mutually exclusive. When both are omitted, Langfuse applies its default production selection.

See Manage prompts with Langfuse for credential setup, selection strategies, caching behavior, and prompt conversion.

capabilities and capability_policy

Capabilities are tags that control which tools the agent can invoke at runtime. Each tool can declare a set of capability tags. The agent's capabilities list declares which tags the agent is allowed to use.

When capability_policy is set to "locked", the agent can only invoke tools whose capability tags are a subset of its declared capabilities. Tools with no declared capabilities are always available.

agent "my_agent" {
  graph {
    type = "react"
  }

  capabilities      = ["math", "filesystem::read"]
  capability_policy = "locked"
  ...
}

See Tools and capabilities for how capabilities work with tools and Control tool access with capabilities for the recipe.

AgentModel

The model block selects the LLM the agent uses.

Field	Type	Required	runtime()	Default	Description
`provider`	string	yes	yes	…	Label of a `provider` block. A constant that matches no `provider` block fails the build; a `runtime()` value that matches none is rejected when the agent selects its model.
`name`	string	yes	yes	…	Model identifier as recognised by the provider.

Inference parameters such as temperature, max_tokens, and top_p are set on the provider block, not here. See Configure a model provider and the provider reference.