> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hellofriday.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# @agent Decorator

> Registers a function as a Friday agent with metadata for discovery and execution.

## Signature

```python theme={null}
@agent(
    *,
    id: str,
    version: str,
    description: str,
    display_name: str | None = None,
    summary: str | None = None,
    constraints: str | None = None,
    examples: list[str] | None = None,
    input_schema: type | None = None,
    output_schema: type | None = None,
    environment: dict[str, Any] | None = None,
    mcp: dict[str, Any] | None = None,
    llm: dict[str, Any] | None = None,
    use_workspace_skills: bool = False,
)
def execute(prompt: str, ctx: AgentContext) -> OkResult | ErrResult:
    ...
```

## Required Parameters

The build API validates that all three are present. Missing any returns HTTP 400 with `"phase": "validate"`.

### `id`

* **Type:** `str`
* **Description:** Unique identifier for the agent. Use kebab-case.
* **Constraints:** Must be unique within your space.
* **Example:** `"text-analyzer"`, `"github-helper"`, `"jira-operations"`

### `version`

* **Type:** `str`
* **Description:** Semantic version of the agent.
* **Example:** `"1.0.0"`, `"2.1.0-alpha.1"`
* **Behaviour:** Multiple versions coexist on disk; Friday resolves the ID to the highest semver version.

### `description`

* **Type:** `str`
* **Description:** What the agent does. Used by the planner for delegation decisions.
* **Guidance:** Be specific about capabilities and use cases. 50-200 characters.
* **Required:** Build fails without this field.

## Optional Parameters

### `display_name`

* **Type:** `str | None`
* **Description:** Human-readable name for the UI. Falls back to `id` if not provided.

### `summary`

* **Type:** `str | None`
* **Description:** One-line summary for agent listings.

### `constraints`

* **Type:** `str | None`
* **Description:** Limitations, requirements, or conditions for using the agent.
* **Example:** `"Requires GitHub token. Cannot access space database tables."`

### `examples`

* **Type:** `list[str] | None`
* **Description:** Example prompts that trigger this agent. Helps the planner learn delegation patterns.

```python theme={null}
examples=[
    "Write a Python function to parse JSON",
    "Debug this error in the codebase",
    "Analyse stack traces and identify root causes",
]
```

### `input_schema`

* **Type:** `type | None`
* **Description:** Dataclass type for structured input parsing. Currently informational; used for documentation generation.

### `output_schema`

* **Type:** `type | None`
* **Description:** Dataclass type for structured output. Passed to agent via `ctx.output_schema`.

### `use_workspace_skills`

* **Type:** `bool`
* **Default:** `False`
* **Description:** Whether the agent loads space skills before execution.

## Environment Configuration

### `environment`

* **Type:** `dict[str, Any] | None`
* **Description:** Environment variable requirements.

```python theme={null}
environment={
    "required": [
        {
            "name": "API_KEY",
            "description": "API authentication token",
            "linkRef": {"provider": "anthropic", "key": "api_key"},  # Optional
        },
    ],
    "optional": [
        {
            "name": "DEBUG",
            "description": "Enable debug logging",
        },
    ],
}
```

Access in agent code via `ctx.env["API_KEY"]`.

## MCP Configuration

### `mcp`

* **Type:** `dict[str, Any] | None`
* **Description:** MCP servers to launch alongside the agent.

```python theme={null}
mcp={
    "github": {
        "transport": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-github"],
            "env": {
                "GITHUB_TOKEN": "your-github-token",
            },
        }
    },
    "time": {
        "transport": {
            "type": "stdio",
            "command": "uvx",
            "args": ["mcp-server-time", "--local-timezone", "UTC"],
        }
    },
}
```

## LLM Configuration

### `llm`

* **Type:** `dict[str, Any] | None`
* **Description:** Default LLM provider and model for the agent.

```python theme={null}
llm={
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
}
```

Used when `ctx.llm.generate()` is called without explicit model. See [How to Call LLMs](/sdk/guides/call-llms) for resolution order.

## Handler Function Signature

The decorated function receives:

```python theme={null}
def execute(prompt: str, ctx: AgentContext) -> OkResult | ErrResult:
    ...
```

### Parameters

* `prompt` - The enriched prompt string from Friday (includes task, context, temporal facts)
* `ctx` - [AgentContext](/sdk/python-reference/agent-context) with capabilities and metadata

### Return Types

Return either:

* `ok(data)` - Success with structured data
* `ok(data, extras=AgentExtras(...))` - Success with metadata
* `err(message)` - Failure with error message

## Example

```python theme={null}
from friday_agent_sdk import agent, ok, err, AgentContext

@agent(
    id="code-analyzer",
    version="1.2.0",
    description="Analyses code for bugs, security issues, and style violations",
    summary="Static analysis agent for code review",
    constraints="Requires read access to repository files. Does not execute code.",
    examples=[
        "Analyse this function for security vulnerabilities",
        "Check this code for SQL injection risks",
        "Review this PR for common anti-patterns",
    ],
    environment={
        "required": [
            {"name": "GITHUB_TOKEN", "description": "For accessing private repos"},
        ],
    },
    mcp={
        "github": {
            "transport": {
                "type": "stdio",
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-github"],
            }
        }
    },
    llm={"provider": "anthropic", "model": "claude-sonnet-4-6"},
)
def execute(prompt: str, ctx: AgentContext):
    # Implementation
    return ok({"issues": []})
```

## Registration Validation

When you register an agent, the daemon validates metadata. Errors return:

```json theme={null}
{
  "ok": false,
  "phase": "validate",
  "error": "description is required"
}
```

## Version Semantics

Agent versions follow [Semantic Versioning](https://semver.org/):

* `MAJOR` - Breaking changes to agent behavior
* `MINOR` - New capabilities, backwards compatible
* `PATCH` - Bug fixes, backwards compatible

Friday resolves agent references to the latest semver version:

```python theme={null}
# Build v1.0.0
curl -F "files=@agent.py" ...  # version="1.0.0"

# Build v1.0.1
curl -F "files=@agent.py" ...  # version="1.0.1"

# Reference in workspace.yml
agents:
  my-agent:
    type: user    # Resolves to v1.0.1 (latest)
```

Both versions remain on disk; rollback is possible by adjusting the space reference or rebuilding with a downgraded version.

## See Also

<CardGroup cols={3}>
  <Card title="AgentContext" icon="gear" href="/sdk/python-reference/agent-context">
    Execution context and capabilities
  </Card>

  <Card title="Result Types" icon="code" href="/sdk/python-reference/result-types">
    ok() and err() constructors
  </Card>

  <Card title="How to Use MCP Tools" icon="wrench" href="/sdk/guides/use-mcp-tools">
    Task-oriented guide for MCP tool integration
  </Card>
</CardGroup>