@agent Decorator

@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:
    ...

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

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

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={
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
}

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

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": []})

{
  "ok": false,
  "phase": "validate",
  "error": "description is required"
}

# 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)