Skip to main content

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.

​
Signature

@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 workspace.
  • 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 workspace database tables."

​
examples

  • Type: list[str] | None
  • Description: Example prompts that trigger this agent. Helps the planner learn delegation patterns.
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 workspace skills before execution.

​
Environment Configuration

​
environment

  • Type: dict[str, Any] | None
  • Description: Environment variable requirements.
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.
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.
llm={
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
}
Used when ctx.llm.generate() is called without explicit model. See How to Call LLMs for resolution cascade.

​
Handler Function Signature

The decorated function receives: 
def execute(prompt: str, ctx: AgentContext) -> OkResult | ErrResult:
    ...

​
Parameters

  • prompt — The enriched prompt string from Friday (includes task, context, temporal facts)
  • ctx — AgentContext 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

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: 
{
  "ok": false,
  "phase": "validate",
  "error": "description is required"
}

​
Version Semantics

Agent versions follow Semantic Versioning:
  • 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: 
# 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
    agent: "my-agent"    # Resolves to v1.0.1 (latest)
Both versions remain on disk; rollback is possible by adjusting the workspace reference or rebuilding with a downgraded version.

​
See Also

AgentContext

Execution context and capabilities

Result Types

ok() and err() constructors

How to Use MCP Tools

Task-oriented guide for MCP tool integration