Quickstart

Build a text analysis agent that accepts a topic and returns a structured analysis with a summary, key points, and a sentiment rating. It demonstrates:

The @agent decorator for metadata
Calling an LLM through ctx.llm.generate_object() for structured output
Returning structured data with ok()

Prerequisites

Friday Studio installed and running - daemon reachable at http://localhost:18080
Python 3.11+ and uv (for IDE support)
A text editor (VS Code recommended)

Step 1: Set up IDE support

You need the SDK installed locally for autocomplete and type checking. Create a Python environment and install the SDK:

# 1. Clone the SDK somewhere (one-time)
git clone git@github.com:friday-platform/agent-sdk.git ~/agent-sdk

# 2. Create a venv in your agent project directory
mkdir -p ~/my-agents && cd ~/my-agents
uv venv
source .venv/bin/activate
uv pip install -e ~/agent-sdk/packages/python

VS Code configuration (optional)

Create .vscode/settings.json in your agent directory:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.analysis.typeCheckingMode": "basic"
}

Reload VS Code after creating the file. Cmd+click on AgentContext in the next step should jump to the SDK definition.

Step 2: Create the agent file

Create a directory for your agent anywhere on your machine:

mkdir -p ~/my-agents/text-analyzer

This agent accepts text input and returns structured analysis. It uses:

A @dataclass to define the output shape
ctx.llm.generate_object() to request structured JSON from an LLM
The host’s LLM provider - your code never handles API keys

Write ~/my-agents/text-analyzer/agent.py:

from dataclasses import dataclass
from friday_agent_sdk import agent, ok, AgentContext, run
@dataclass
class AnalysisResult:
    summary: str
    key_points: list[str]
    sentiment: str  # "positive", "negative", or "neutral"


@agent(
    id="text-analyzer",
    version="1.0.0",
    description="Analyzes text and returns structured summary, key points, and sentiment",
)
def execute(prompt: str, ctx: AgentContext):
    """Analyze the user's text using an LLM."""

    # Define the schema for structured output
    output_schema = {
        "type": "object",
        "properties": {
            "summary": {"type": "string"},
            "key_points": {
                "type": "array",
                "items": {"type": "string"},
            },
            "sentiment": {
                "type": "string",
                "enum": ["positive", "negative", "neutral"],
            },
        },
        "required": ["summary", "key_points", "sentiment"],
        "additionalProperties": False,
    }

    # Call Friday's LLM provider - your agent never sees the API key
    analysis_prompt = f"""Analyze the following text.

Text:
{prompt}

Provide a concise summary, 3-5 key points, and an overall sentiment."""

    result = ctx.llm.generate_object(
        messages=[{"role": "user", "content": analysis_prompt}],
        schema=output_schema,
        model="anthropic:claude-haiku-4-5",  # Fast and cost-effective
    )

    # result.object contains the parsed JSON matching our schema
    return ok(result.object)


if __name__ == "__main__":
    run()

Step 3: Build and test

friday agent register ~/my-agents/text-analyzer

The daemon validates the agent, copies source files, and hot-reloads the registry. No restart required. Verify the registration succeeded:

friday agent list | grep text-analyzer
# text-analyzer@1.0.0

Test your agent with the CLI (requires Studio running at http://localhost:15200):

friday agent exec text-analyzer \
  -i "The new feature shipped on time and customers report faster load times. Support tickets are down 40%."

Or hit the daemon directly:

curl -s -X POST http://localhost:18080/api/agents/text-analyzer/run \
  -H 'Content-Type: application/json' \
  -d '{"input": "The new feature shipped on time and customers report faster load times. Support tickets are down 40%."}' | jq .

The response streams as SSE events. After a moment you see the result:

{
  "summary": "Product launch successful with measurable performance improvements",
  "key_points": [
    "Feature shipped on schedule",
    "Load times significantly improved",
    "Support tickets decreased by 40%"
  ],
  "sentiment": "positive"
}

Try a different input:

friday agent exec text-analyzer \
  -i "The server crashed twice today. The database is throwing connection errors and the logs are incomprehensible."

Your agent classifies this as "sentiment": "negative".

Add --json for raw NDJSON output, useful for piping to jq:

friday agent exec text-analyzer -i "analyze this text" --json | jq .

Step 4: Iterate

Edit ~/my-agents/text-analyzer/agent.py, then re-register and test:

friday agent register ~/my-agents/text-analyzer
friday agent exec text-analyzer -i "test your changes"

This cycle - edit, restart, test - is your development loop.

There’s a skill for that. The writing-friday-python-agents skill lets coding agents like Claude Code write and modify Friday agents directly - correct imports and proper capability calls.

Bump the version to keep old builds available for rollback:

@agent(
    id="text-analyzer",
    version="1.0.1",  # Bumped from 1.0.0
    description="Analyzes text with an LLM",
)

Both versions are stored, but Friday resolves text-analyzer to the latest semver version (1.0.1).

Step 5: Register in a space (optional)

To use your agent within a Friday space (for planner routing, signals, and multi-agent orchestration), add it to your space’s workspace.yml:

workspace.yml

agents:
  text-analyzer:
    type: user

The type: user field tells Friday this is a custom Python agent. The id must match the id in the @agent decorator. This step is not required for direct execution.

Advanced topics

Using the HTTP API directly

For CI/CD pipelines or automation, register agents via the daemon API on port 18080:

curl -X POST http://localhost:18080/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{"entrypoint": "/abs/path/to/agent.py"}' \
  | jq .

Error responses include the phase that failed (prereqs, validate, or write):

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

Troubleshooting

Agent not found after registering - Check that registration returned {"ok": true, ...}. Verify the agent ID matches what you pass to the execute command. Run friday agent list to see all registered agents.Build fails with syntax errors - The SDK uses pure Python dataclasses - no Pydantic. Ensure your type hints use standard library types only.Registration returns 400 - Your @agent decorator metadata failed validation. Required fields: id, version, description.ImportError on third-party packages - Ensure the package is installed in the agent’s Python environment. You can pip install additional pure-Python packages. Use ctx.http and ctx.llm for I/O that needs host audit logging and credential management.Credentials not working - Verify your .env file contains ANTHROPIC_API_KEY and re-register the agent: friday agent register /abs/path/to/agent.py.

Next steps

Call LLMs

Different models, structured output, and error handling.

Make HTTP requests

Fetch data from external APIs.

Use MCP tools

Invoke GitHub, databases, and other MCP servers.

How agents work

The subprocess model and host capabilities.

Getting started

Core concepts

Guides

Agent SDK

Reference

Resources

Prerequisites

Step 1: Set up IDE support

Step 2: Create the agent file

Step 3: Build and test

Step 4: Iterate

Step 5: Register in a space (optional)

Advanced topics

Next steps

Call LLMs

Make HTTP requests

Use MCP tools

How agents work

​Prerequisites

​Step 1: Set up IDE support

​Step 2: Create the agent file

​Step 3: Build and test

​Step 4: Iterate

​Step 5: Register in a space (optional)

​Advanced topics

​Next steps

Call LLMs

Make HTTP requests

Use MCP tools

How agents work

Prerequisites

Step 1: Set up IDE support

Step 2: Create the agent file

Step 3: Build and test

Step 4: Iterate

Step 5: Register in a space (optional)

Advanced topics

Next steps