### Quickstart Python Agent Example
Source: https://docs.hellofriday.ai/sdk/python
A simple Python agent that summarizes text using an LLM. It includes the @agent decorator for metadata and the run() call for connecting to the daemon.
```python
from friday_agent_sdk import agent, ok, AgentContext, run
@agent(
id="my-agent",
version="1.0.0",
description="Summarizes text with an LLM",
)
def execute(prompt: str, ctx: AgentContext):
result = ctx.llm.generate(
messages=[{"role": "user", "content": f"Summarize this: {prompt}"}],
model="anthropic:claude-haiku-4-5",
)
return ok({"summary": result.text})
if __name__ == "__main__":
run()
```
--------------------------------
### Real Example: Time Operations
Source: https://docs.hellofriday.ai/sdk/python-reference/tools-capability
A practical example demonstrating the configuration of an MCP server for time operations and the subsequent use of `ctx.tools.list()` and `ctx.tools.call()` to get and convert time.
```APIDOC
## Real Example: Time Operations
### Description
Demonstrates configuring an MCP server for time operations and using tools to get and convert time.
### Example
```python
@agent(
id="time-agent",
version="1.0.0",
description="Time conversion",
mcp={
"time": {
"transport": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-time", "--local-timezone", "UTC"],
}
}
},
)
def execute(prompt, ctx):
# Discover available tools
tools = ctx.tools.list()
tool_names = [t.name for t in tools]
# Call current time
now = ctx.tools.call("get_current_time", {{"timezone": "UTC"}})
# Convert time
converted = ctx.tools.call(
"convert_time",
{
"source_timezone": "UTC",
"time": "14:30",
"target_timezone": "America/New_York",
},
)
return ok({
"current_utc": now,
"converted": converted,
"available_tools": tool_names,
})
```
```
--------------------------------
### Agent Examples Configuration
Source: https://docs.hellofriday.ai/sdk/python-reference/agent-decorator
Provide example prompts to help the planner learn delegation patterns for this agent.
```python
examples=[
"Write a Python function to parse JSON",
"Debug this error in the codebase",
"Analyse stack traces and identify root causes",
]
```
--------------------------------
### Basic GET Request
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Example of making a basic GET request and handling the response.
```APIDOC
## Basic GET
### Description
Example of making a basic GET request and handling the response.
### Code
```python
response = ctx.http.fetch("https://api.example.com/data")
if response.status == 200:
data = response.json()
return ok({"data": data})
elif response.status == 404:
return ok({"found": False})
else:
return err(f"API error: {response.status}")
```
```
--------------------------------
### Create Virtual Environment and Install SDK
Source: https://docs.hellofriday.ai/sdk/python
Creates a Python virtual environment and installs the Friday agent SDK locally. This enables IDE support for autocomplete and type checking.
```bash
cd my-agent-project
uv venv
source .venv/bin/activate # or: .venv\Scripts\activate on Windows
uv pip install -e ~/agent-sdk/packages/python
```
--------------------------------
### Real Example: Time Operations with MCP Server
Source: https://docs.hellofriday.ai/sdk/guides/use-mcp-tools
This agent demonstrates calling time-related tools. It configures a 'time' MCP server and uses `ctx.tools.call` to get the current time in a specific timezone and convert time between timezones.
```python
@agent(
id="time-agent",
version="1.0.0",
description="Time conversion agent",
mcp={
"time": {
"transport": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-time", "--local-timezone", "UTC"],
}
}
},
)
def execute(prompt, ctx):
# Get current time in Tokyo
result = ctx.tools.call(
"get_current_time",
{"timezone": "Asia/Tokyo"},
)
# Convert time
converted = ctx.tools.call(
"convert_time",
{
"source_timezone": "UTC",
"time": "14:30",
"target_timezone": "America/New_York",
},
)
return ok({
"tokyo_time": result,
"converted": converted,
})
```
--------------------------------
### Agent Versioning and Deployment Example
Source: https://docs.hellofriday.ai/sdk/python-reference/agent-decorator
This example demonstrates how to build and reference agent versions using curl commands and a workspace configuration file, illustrating semantic versioning (MAJOR.MINOR.PATCH) and how Friday resolves agent references to the latest semver version.
```shell
# 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:
- id: my-agent
type: user # Resolves to v1.0.1 (latest)
```
--------------------------------
### Tool Chaining Example
Source: https://docs.hellofriday.ai/sdk/guides/use-mcp-tools
Demonstrates how to chain multiple tool calls. This example first finds a specific tool ('search_issues') by name and then calls it with provided arguments.
```python
# Chain multiple tool calls
tools = ctx.tools.list()
# Find relevant tool by name
search_tool = next((t for t in tools if t.name == "search_issues"), None)
if not search_tool:
return err("search_issues tool not available")
# Search
issues = ctx.tools.call("search_issues", {"query": prompt})
```
--------------------------------
### Real Example: Multi-Phase Agent
Source: https://docs.hellofriday.ai/sdk/guides/stream-progress
This example demonstrates a multi-phase agent that uses ctx.stream.progress() to report progress across different stages, including LLM calls and tool usage.
```python
from friday_agent_sdk import agent, ok, AgentExtras
@agent(id="analyzer", version="1.0.0", description="Multi-phase analysis")
def execute(prompt, ctx):
# Phase 1: Extract parameters
ctx.stream.progress("Parsing request")
params = extract_params(prompt)
# Phase 2: LLM preprocessing
ctx.stream.progress("Running initial analysis", tool_name="LLM")
analysis = ctx.llm.generate(
messages=[{"role": "user", "content": f"Analyze: {params}"}],
model="claude-haiku-4-5",
)
# Phase 3: Tool calls
ctx.stream.progress("Fetching related data", tool_name="GitHub")
issues = ctx.tools.call("search_issues", {"query": params["query"]})
# Phase 4: Synthesis
ctx.stream.progress("Synthesizing results", tool_name="Synthesizer")
result = synthesize(analysis.text, issues)
ctx.stream.progress("Analysis complete")
return ok({
"summary": result["summary"],
"recommendations": result["recommendations"],
})
```
--------------------------------
### Install Friday AI SDK
Source: https://docs.hellofriday.ai/sdk/quickstart
Clone the SDK and install it locally in your agent project's virtual environment using uv. This enables IDE support like autocomplete and type checking.
```bash
# 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
```
--------------------------------
### List Agents using cURL
Source: https://docs.hellofriday.ai/api-reference/agents/list-agents
Example of how to list all available agents using cURL. This command sends a GET request to the /api/agents endpoint.
```bash
curl http://localhost:18080/api/agents
```
--------------------------------
### Jira Agent Example with parse_operation()
Source: https://docs.hellofriday.ai/sdk/guides/handle-structured-input
A real-world example demonstrating how to use `parse_operation()` with multiple Jira-related operations and their corresponding schemas.
```python
from dataclasses import dataclass
from friday_agent_sdk import agent, err, ok, parse_operation
@dataclass
class IssueViewConfig:
operation: str
issue_key: str
@dataclass
class IssueSearchConfig:
operation: str
jql: str
max_results: int = 50
@dataclass
class IssueCreateConfig:
operation: str
project_key: str
summary: str
description: str | None = None
issue_type: str = "Bug"
OPERATION_SCHEMAS = {
"issue-view": IssueViewConfig,
"issue-search": IssueSearchConfig,
"issue-create": IssueCreateConfig,
}
@agent(id="jira", version="1.0.0", description="Jira operations")
def execute(prompt, ctx):
try:
config = parse_operation(prompt, OPERATION_SCHEMAS)
except ValueError as e:
return err(str(e))
match config.operation:
case "issue-view":
return _view_issue(config, ctx)
case "issue-search":
return _search_issues(config, ctx)
case "issue-create":
return _create_issue(config, ctx)
```
--------------------------------
### Verify friday CLI installation
Source: https://docs.hellofriday.ai/core-concepts/cli
Check if the friday CLI is installed and accessible by running the version command.
```shell
friday version
```
--------------------------------
### Configuration Example
Source: https://docs.hellofriday.ai/sdk/python-reference/tools-capability
Demonstrates how to configure MCP servers, including transport details and environment variables, within the @agent decorator.
```APIDOC
## Configuration
### Description
MCP servers are configured in the `@agent` decorator.
### Example
```python
@agent(
id="github-helper",
version="1.0.0",
description="Uses GitHub",
mcp={
"github": {
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "your-github-token",
},
}
}
},
)
def execute(prompt, ctx):
# ctx.tools.list() includes tools from github server
result = ctx.tools.call("search_issues", {{...}})
...
```
```
--------------------------------
### Request Headers Example
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Shows how to set custom request headers and access response headers.
```python
response = ctx.http.fetch(
url,
headers={
"Accept": "application/json",
"User-Agent": "my-agent/1.0",
"X-Custom-Header": "value",
},
)
# Access response headers
content_type = response.headers.get("content-type", "")
rate_limit = response.headers.get("x-ratelimit-remaining")
```
--------------------------------
### Dynamic Tool Selection Example
Source: https://docs.hellofriday.ai/sdk/python-reference/tools-capability
Demonstrates how to dynamically select and call a tool based on the user's prompt.
```APIDOC
## Dynamic Tool Selection
### Description
Dynamically select an appropriate tool based on the input prompt.
### Example
```python
def execute(prompt, ctx):
tools = ctx.tools.list()
# Find appropriate tool based on prompt
if "issue" in prompt.lower():
tool = next((t for t in tools if "issue" in t.name), None)
elif "pr" in prompt.lower() or "pull" in prompt.lower():
tool = next((t for t in tools if "pull" in t.name), None)
else:
return err("No appropriate tool found")
if not tool:
available = [t.name for t in tools]
return err(f"Tool not found. Available: {{available}}")
result = ctx.tools.call(tool.name, {{"query": prompt}})
return ok({{"result": result}})
```
```
--------------------------------
### Memory Block Example
Source: https://docs.hellofriday.ai/core-concepts/memory
This XML snippet shows how memory entries are displayed within an agent's context, typically injected at the start of a session.
```xml
- PR review for myorg/myrepo #42 completed — 2 critical findings (2026-04-29)
- User prefers compact summaries
```
--------------------------------
### Start Friday Daemon
Source: https://docs.hellofriday.ai/core-concepts/cli
Start the Friday daemon. It can be run in the background using the `--detached` flag and configured with a specific port.
```bash
friday daemon start --detached
```
```bash
friday daemon start --detached --port 18080
```
--------------------------------
### Phase-Based Progress Example
Source: https://docs.hellofriday.ai/sdk/python-reference/stream-capability
Demonstrates how to use the `progress` method to show multi-phase progress updates during a complex operation.
```APIDOC
## Common Usage Patterns
### Phase-Based Progress
```python theme={null}
def execute(prompt, ctx):
ctx.stream.progress("Phase 1: Parsing input")
config = parse_input(prompt)
ctx.stream.progress("Phase 2: Fetching data", tool_name="GitHub")
data = ctx.tools.call("fetch_repo", config)
ctx.stream.progress("Phase 3: Analysing", tool_name="LLM")
analysis = ctx.llm.generate(...)
ctx.stream.progress("Phase 4: Finalising")
return ok({"result": analysis.text})
```
```
--------------------------------
### Get Agent Details (cURL)
Source: https://docs.hellofriday.ai/api-reference/agents/get-agent-details
Example of how to fetch agent details using cURL. Replace `slack` with the desired agent ID.
```bash
curl http://localhost:18080/api/agents/slack
```
--------------------------------
### Basic Text Generation with ctx.llm.generate()
Source: https://docs.hellofriday.ai/sdk/guides/call-llms
Use `ctx.llm.generate()` for simple text completion. This example shows how to prompt an LLM to write documentation based on a given input.
```python
from friday_agent_sdk import agent, ok
@agent(id="writer", version="1.0.0", description="Writes documentation")
def execute(prompt, ctx):
result = ctx.llm.generate(
messages=[{"role": "user", "content": f"Write docs for: {prompt}"}],
model="anthropic:claude-sonnet-4-6",
)
return ok({"output": result.text})
```
--------------------------------
### Finding Tools Example
Source: https://docs.hellofriday.ai/sdk/python-reference/tools-capability
Shows how to filter the list of available tools by name patterns.
```APIDOC
## Finding Tools
### Description
Filter tools by name pattern.
### Example
```python
tools = ctx.tools.list()
search_tools = [t for t in tools if "search" in t.name]
git_tools = [t for t in tools if t.name.startswith("git")]
```
```
--------------------------------
### Query Parameters
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Shows how to construct URLs with query parameters for GET requests.
```APIDOC
## Query Parameters
Construct URL with parameters:
```python
import urllib.parse
params = {"q": "search query", "limit": 10}
query = urllib.parse.urlencode(params)
url = f"https://api.example.com/search?{query}"
response = ctx.http.fetch(url)
```
```
--------------------------------
### Basic HTTP Operations
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Demonstrates common HTTP operations: GET collection, GET item, POST create, PUT update, and DELETE. Ensure you have the base URL and item ID defined.
```python
response = ctx.http.fetch(f"{base_url}/items")
items = response.json()["items"]
```
```python
response = ctx.http.fetch(f"{base_url}/items/{item_id}")
item = response.json()
```
```python
response = ctx.http.fetch(
f"{base_url}/items",
method="POST",
headers={"Content-Type": "application/json"},
body=json.dumps({"name": "New"}),
)
new_item = response.json()
```
```python
response = ctx.http.fetch(
f"{base_url}/items/{item_id}",
method="PUT",
headers={"Content-Type": "application/json"},
body=json.dumps({"name": "Updated"}),
)
```
```python
response = ctx.http.fetch(
f"{base_url}/items/{item_id}",
method="DELETE",
)
```
--------------------------------
### List Sessions using cURL
Source: https://docs.hellofriday.ai/api-reference/sessions/list-sessions
Example of how to list all session summaries using cURL. The request is made to the local daemon's /api/sessions endpoint.
```bash
curl http://localhost:18080/api/sessions
```
--------------------------------
### Fallback When Unavailable Example
Source: https://docs.hellofriday.ai/sdk/python-reference/stream-capability
Demonstrates a safe way to use `ctx.stream` by checking its existence, ensuring it functions as a no-op in test contexts.
```APIDOC
### Fallback When Unavailable
`ctx.stream` is always present. It is a safe no-op in test contexts:
```python theme={null}
def execute(prompt, ctx):
# Safe wrapper
def progress(msg, tool=None):
if ctx.stream:
ctx.stream.progress(msg, tool_name=tool)
progress("Starting...")
# Work...
progress("Complete")
return ok({"done": True})
```
```
--------------------------------
### Tool-Associated Progress Example
Source: https://docs.hellofriday.ai/sdk/python-reference/stream-capability
Shows how to associate progress messages with specific tools using the `tool_name` parameter in the `progress` method.
```APIDOC
### Tool-Associated Progress
```python theme={null}
def execute(prompt, ctx):
ctx.stream.progress("Initialising", tool_name="Setup")
ctx.stream.progress("Querying database", tool_name="PostgreSQL")
rows = ctx.tools.call("query", {"sql": "SELECT ..."})
ctx.stream.progress("Processing results", tool_name="Processor")
processed = [transform(r) for r in rows]
ctx.stream.progress("Storing analysis", tool_name="Storage")
ctx.http.fetch(..., method="POST", body=json.dumps(processed))
ctx.stream.progress("Complete", tool_name="Setup")
return ok({"count": len(processed)})
```
```
--------------------------------
### Get Space Details
Source: https://docs.hellofriday.ai/api-reference/spaces/get-space-details
Fetches the details and configuration for a given workspace ID.
```APIDOC
## GET /api/workspaces/{workspaceId}
### Description
Get a space's details and configuration.
### Method
GET
### Endpoint
/api/workspaces/{workspaceId}
### Parameters
#### Path Parameters
- **workspaceId** (string) - Required - The ID of the workspace to retrieve.
#### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the workspace.
- **name** (string) - The name of the workspace.
- **description** (string) - A description of the workspace.
- **status** (string) - The current status of the workspace (e.g., 'active').
- **path** (string) - The file path associated with the workspace.
- **createdAt** (string) - The date and time the workspace was created.
- **lastSeen** (string) - The date and time the workspace was last seen.
- **config** (object) - The full workspace configuration (nullable).
- **type** (string) - The type of the workspace ('ephemeral' or 'persistent').
#### Response Example
```json
{
"id": "abc123",
"name": "my-space",
"description": "My first space",
"status": "active",
"path": "/path/to/space",
"createdAt": "2023-10-27T10:00:00Z",
"lastSeen": "2023-10-27T10:30:00Z",
"config": {
"setting1": "value1"
},
"type": "persistent"
}
```
#### Error Response (404)
- **description**: Space not found
```
--------------------------------
### Constructing URL with Query Parameters
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Shows how to build a URL with query parameters using `urllib.parse.urlencode`. This is useful for GET requests that require filtering or pagination.
```python
import urllib.parse
params = {"q": "search query", "limit": 10}
query = urllib.parse.urlencode(params)
url = f"https://api.example.com/search?{query}"
response = ctx.http.fetch(url)
```
--------------------------------
### Error Handling Example
Source: https://docs.hellofriday.ai/sdk/python-reference/tools-capability
Illustrates how to handle `ToolCallError` exceptions that may occur during tool execution.
```APIDOC
## Error Handling
### Description
Handles potential errors during tool execution using a try-except block.
### Example
```python
from friday_agent_sdk import ToolCallError, agent, err, ok
@agent(id="safe-caller", version="1.0.0", description="Handles tool errors")
def execute(prompt, ctx):
try:
result = ctx.tools.call("risky_operation", {{"data": prompt}})
except ToolCallError as e:
return err(f"Tool failed: {{e}}")
return ok({{"result": result}})
```
```
--------------------------------
### Intent for State Changes Example
Source: https://docs.hellofriday.ai/sdk/python-reference/stream-capability
Illustrates using the `intent` method to signal significant state changes or user-focused actions within the application flow.
```APIDOC
### Intent for State Changes
```python theme={null}
def execute(prompt, ctx):
ctx.stream.intent("Understanding task requirements")
requirements = extract_requirements(prompt)
ctx.stream.intent("Planning approach")
plan = create_plan(requirements)
ctx.stream.intent("Executing plan")
for step in plan.steps:
ctx.stream.progress(f"Step {step.number}: {step.description}")
execute_step(step)
ctx.stream.intent("Finalising results")
return ok({"completed": True})
```
```
--------------------------------
### HTTP Request Authentication
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Examples of how to authenticate HTTP requests using different methods. Ensure the URL and necessary environment variables (like TOKEN or API_KEY) are configured.
```python
# Bearer token
response = ctx.http.fetch(
url,
headers={"Authorization": f"Bearer {ctx.env['TOKEN']}"},
)
```
```python
# Basic auth (construct manually)
import base64
credentials = base64.b64encode(b"user:pass").decode()
response = ctx.http.fetch(
url,
headers={"Authorization": f"Basic {credentials}"},
)
```
```python
# API key in header
response = ctx.http.fetch(
url,
headers={"X-API-Key": ctx.env['API_KEY']},
)
```
--------------------------------
### Get Space Details (OpenAPI Specification)
Source: https://docs.hellofriday.ai/api-reference/spaces/get-space-details
This OpenAPI 3.1.0 specification defines the GET /api/workspaces/{workspaceId} endpoint for retrieving space details. It includes parameters, response schemas, and an example.
```yaml
openapi: 3.1.0
info:
title: Friday Platform API
description: >-
The Friday daemon HTTP API for managing spaces, agents, sessions, and
automations.
version: 1.0.0
servers:
- url: http://localhost:18080
description: Local Friday daemon
security: []
tags:
- name: Health
description: Daemon health and status
- name: Spaces
description: Space management
- name: Chat
description: Conversational AI
- name: Sessions
description: Execution session management
- name: Signals
description: Trigger management
- name: Agents
description: Agent discovery and inspection
- name: Artifacts
description: File and data artifact management
- name: Configuration
description: Daemon configuration
paths:
/api/workspaces/{workspaceId}:
get:
tags:
- Spaces
summary: Get space details
description: Get a space's details and configuration.
operationId: getWorkspace
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
responses:
'200':
description: Space details
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/WorkspaceInfo'
- type: object
properties:
config:
type: object
description: Full workspace configuration
nullable: true
type:
type: string
enum:
- ephemeral
- persistent
'404':
description: Space not found
x-codeSamples:
- lang: bash
label: cURL
source: curl http://localhost:18080/api/workspaces/abc123
components:
schemas:
WorkspaceInfo:
type: object
properties:
id:
type: string
example: abc123
name:
type: string
example: my-space
description:
type: string
example: My first space
status:
type: string
example: active
path:
type: string
createdAt:
type: string
format: date-time
lastSeen:
type: string
format: date-time
```
--------------------------------
### Basic GET Request
Source: https://docs.hellofriday.ai/sdk/guides/make-http-requests
Perform a simple GET request to an API endpoint. Handles basic success and error status codes.
```python
from friday_agent_sdk import agent, ok
@agent(id="fetcher", version="1.0.0", description="Fetches data from APIs")
def execute(prompt, ctx):
response = ctx.http.fetch("https://api.example.com/data")
if response.status >= 400:
return err(f"API error {response.status}")
data = response.json() # Convenience helper
return ok({"data": data})
```
--------------------------------
### Configure WhatsApp Credentials Inline in workspace.yml
Source: https://docs.hellofriday.ai/core-concepts/communicators/whatsapp
Paste your WhatsApp credentials directly into the `workspace.yml` file for a fully scripted setup. Ensure the `api_version` is set if not using the default.
```yaml
communicators:
whatsapp:
kind: whatsapp
access_token: "EAA..."
app_secret: "0ad6c116..."
phone_number_id: "15551234567"
verify_token: ""
api_version: "v21.0" # optional; defaults to v21.0
```
--------------------------------
### Text Analyzer Agent JSON Output Example
Source: https://docs.hellofriday.ai/sdk/quickstart
Example of the structured JSON output from the text-analyzer agent, detailing summary, key points, and sentiment.
```json
{
"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"
}
```
--------------------------------
### Configure Multiple MCP Servers
Source: https://docs.hellofriday.ai/sdk/guides/use-mcp-tools
An agent can be configured to use multiple MCP servers simultaneously. This example shows how to declare both GitHub and PostgreSQL MCP servers, making tools from both available via `ctx.tools`.
```python
@agent(
id="multi-tool",
version="1.0.0",
description="Uses GitHub and database tools",
mcp={
"github": {
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
}
},
"postgres": {
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://...",
},
}
}
},
)
def execute(prompt, ctx):
tools = ctx.tools.list()
# Tools from both servers are available
github_tools = [t for t in tools if "github" in t.name]
db_tools = [t for t in tools if "postgres" in t.name]
...
```
--------------------------------
### Get Agent Details (OpenAPI)
Source: https://docs.hellofriday.ai/api-reference/agents/get-agent-details
OpenAPI specification for the GET /api/agents/{id} endpoint. This defines the request parameters, expected responses, and response schema for retrieving agent details.
```yaml
openapi: 3.1.0
info:
title: Friday Platform API
description: >-
The Friday daemon HTTP API for managing spaces, agents, sessions, and
automations.
version: 1.0.0
servers:
- url: http://localhost:18080
description: Local Friday daemon
security: []
tags:
- name: Health
description: Daemon health and status
- name: Spaces
description: Space management
- name: Chat
description: Conversational AI
- name: Sessions
description: Execution session management
- name: Signals
description: Trigger management
- name: Agents
description: Agent discovery and inspection
- name: Artifacts
description: File and data artifact management
- name: Configuration
description: Daemon configuration
paths:
/api/agents/{id}:
get:
tags:
- Agents
summary: Get agent details
description: Get detailed information about a specific agent.
operationId: getAgent
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Agent details
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'404':
description: Agent not found
x-codeSamples:
- lang: bash
label: cURL
source: curl http://localhost:18080/api/agents/slack
components:
schemas:
Agent:
type: object
properties:
id:
type: string
example: slack
name:
type: string
example: Slack
description:
type: string
type:
type: string
```
--------------------------------
### HTTP Methods and Options
Source: https://docs.hellofriday.ai/sdk/guides/make-http-requests
Demonstrates how to specify various HTTP methods (PUT, POST, DELETE, etc.), headers, raw string bodies, and timeouts.
```python
response = ctx.http.fetch(
url,
method="PUT", # GET, POST, PUT, PATCH, DELETE, HEAD
headers={...}, # Dict of request headers
body="raw body", # String body
timeout_ms=10000, # Request timeout
)
```
--------------------------------
### Dynamic Tool Selection Based on Prompt
Source: https://docs.hellofriday.ai/sdk/python-reference/tools-capability
Dynamically select an appropriate tool based on keywords in the user's prompt. This example demonstrates finding tools related to 'issue' or 'pr' and handling cases where no suitable tool is found.
```python
def execute(prompt, ctx):
tools = ctx.tools.list()
# Find appropriate tool based on prompt
if "issue" in prompt.lower():
tool = next((t for t in tools if "issue" in t.name), None)
elif "pr" in prompt.lower() or "pull" in prompt.lower():
tool = next((t for t in tools if "pull" in t.name), None)
else:
return err("No appropriate tool found")
if not tool:
available = [t.name for t in tools]
return err(f"Tool not found. Available: {available}")
result = ctx.tools.call(tool.name, {"query": prompt})
return ok({"result": result})
```
--------------------------------
### Guard: Start Daemon if Not Running
Source: https://docs.hellofriday.ai/core-concepts/cli
A common pattern to ensure the Friday daemon is running before executing other commands. It checks the status and starts the daemon in detached mode if it's not active.
```bash
# Guard: start daemon if not running
friday daemon status || friday daemon start --detached
```
--------------------------------
### MCP Server Configuration
Source: https://docs.hellofriday.ai/sdk/python-reference/agent-decorator
Configure Model Context Protocol (MCP) servers to launch alongside the agent.
```python
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"],
}
},
}
```
--------------------------------
### Health Check Response Example
Source: https://docs.hellofriday.ai/core-concepts/api
This is an example of the JSON response received when performing a health check on the Friday daemon. It provides details on active spaces, daemon uptime, and runtime versions.
```json
{
"activeWorkspaces": 3,
"uptime": 3600000,
"timestamp": "2026-03-24T10:00:00.000Z",
"version": { "deno": "...", "v8": "...", "typescript": "..." }
}
```
--------------------------------
### Creating Platform Artifacts via HTTP API
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Demonstrates a common pattern of creating artifacts on the Friday platform using its HTTP API.
```python
import json
response = ctx.http.fetch(
f"{ctx.config.get('platformUrl', 'http://localhost:18080')}/api/artifacts",
method="POST",
headers={"Content-Type": "application/json"},
body=json.dumps({
"data": {
"type": "analysis",
"version": 1,
"data": analysis_result,
},
"title": "Analysis Report",
"summary": "Comprehensive analysis",
}),
)
if response.status < 400:
artifact = response.json().get("artifact", {})
artifact_id = artifact.get("id")
...
```
--------------------------------
### Defensive Programming with AgentContext
Source: https://docs.hellofriday.ai/sdk/python-reference/agent-context
Demonstrates safe access to environment variables and checks for required keys. It shows how to conditionally use LLM generation based on output schema and emit progress updates.
```python
from friday_agent_sdk import agent, ok
@agent(id="safe", version="1.0.0", description="Handles missing capabilities")
def execute(prompt, ctx):
# Safe access with fallbacks
api_key = ctx.env.get("OPTIONAL_KEY") # Returns None if missing
# Required access with check
if "REQUIRED_KEY" not in ctx.env:
return err("REQUIRED_KEY not set. Connect in Friday Link.")
# Capability availability - capabilities are always present
# They raise RuntimeError if called outside the host environment
if ctx.output_schema:
# Structured path
result = ctx.llm.generate_object(...)
else:
# Standard path
result = ctx.llm.generate(...)
# Progress emission - always safe to call
ctx.stream.progress("Working...")
return ok({"result": result.text})
```
--------------------------------
### GET Item
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Fetches a specific item by its ID.
```APIDOC
## GET item
### Description
Fetches a specific item by its ID.
### Method
GET
### Endpoint
/items/{item_id}
### Parameters
#### Path Parameters
- **item_id** (string) - Required - The ID of the item to retrieve.
### Response
#### Success Response (200)
- **id** (string) - The ID of the item.
- **name** (string) - The name of the item.
### Response Example
{
"id": "item1",
"name": "Example Item 1"
}
```
--------------------------------
### Phase-Based Progress Tracking
Source: https://docs.hellofriday.ai/sdk/python-reference/stream-capability
Demonstrates how to use `ctx.stream.progress` to show progress through different phases of an operation, including associating progress with specific tools.
```python
def execute(prompt, ctx):
ctx.stream.progress("Phase 1: Parsing input")
config = parse_input(prompt)
ctx.stream.progress("Phase 2: Fetching data", tool_name="GitHub")
data = ctx.tools.call("fetch_repo", config)
ctx.stream.progress("Phase 3: Analysing", tool_name="LLM")
analysis = ctx.llm.generate(...)
ctx.stream.progress("Phase 4: Finalising")
return ok({"result": analysis.text})
```
--------------------------------
### Get Session
Source: https://docs.hellofriday.ai/llms.txt
Retrieves details for a specific session.
```APIDOC
## Get Session
### Description
Get details of a specific session.
### Method
GET
### Endpoint
/sessions/{session_id}
### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier of the session.
### Response
#### Success Response (200)
- **session_details** (object) - Contains detailed information about the session.
```
--------------------------------
### Supported HTTP Methods
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Demonstrates the usage of different HTTP methods with the `fetch` function.
```APIDOC
## Methods
### Description
All HTTP methods are supported.
### Code
```python
ctx.http.fetch(url, method="GET") # Default
ctx.http.fetch(url, method="POST", body="...")
ctx.http.fetch(url, method="PUT", body="...")
ctx.http.fetch(url, method="PATCH", body="...")
ctx.http.fetch(url, method="DELETE")
ctx.http.fetch(url, method="HEAD")
```
```
--------------------------------
### List Artifacts with cURL
Source: https://docs.hellofriday.ai/api-reference/artifacts/list-artifacts
Demonstrates how to list artifacts using cURL, with a specified limit. This is useful for retrieving a paginated list of artifacts.
```bash
curl 'http://localhost:18080/api/artifacts?limit=10'
```
--------------------------------
### GET Collection
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Fetches a collection of items from the specified URL.
```APIDOC
## GET collection
### Description
Fetches a collection of items.
### Method
GET
### Endpoint
/items
### Response
#### Success Response (200)
- **items** (list) - A list of items.
### Response Example
{
"items": [
{
"id": "item1",
"name": "Example Item 1"
},
{
"id": "item2",
"name": "Example Item 2"
}
]
}
```
--------------------------------
### List Available Tools
Source: https://docs.hellofriday.ai/sdk/python-reference/tools-capability
Iterate through the list of available tools to display their names, descriptions, and input schemas. This is useful for understanding what operations can be performed.
```python
tools = ctx.tools.list()
for tool in tools:
print(f"{tool.name}: {tool.description}")
print(f" Schema: {tool.input_schema}")
```
--------------------------------
### Skill Management
Source: https://docs.hellofriday.ai/core-concepts/cli
Commands for listing, getting, publishing, and managing versions of skills.
```APIDOC
## friday skill list
### Description
List published skills.
### Method
CLI Command
### Endpoint
`friday skill list`
### Parameters
#### Query Parameters
- **--namespace** (string) - Optional - Filter by namespace.
- **--query** (string) - Optional - Search query.
- **--all** (boolean) - Optional - Include disabled skills.
## friday skill get
### Description
Get skill details.
### Method
CLI Command
### Endpoint
`friday skill get`
### Parameters
#### Query Parameters
- **-n** (string) - Required - Skill name in `@namespace/name` format.
## friday skill publish
### Description
Publish a skill from a directory containing a `SKILL.md` file.
### Method
CLI Command
### Endpoint
`friday skill publish`
### Parameters
#### Query Parameters
- **-p** (string) - Optional - Path to skill directory (default: `.`).
- **--name** (string) - Optional - Override skill name from `SKILL.md` frontmatter.
## friday skill versions
### Description
List all versions of a skill.
### Method
CLI Command
### Endpoint
`friday skill versions`
### Parameters
#### Query Parameters
- **-n** (string) - Required - Skill name in `@namespace/name` format.
```
--------------------------------
### Get Artifact
Source: https://docs.hellofriday.ai/llms.txt
Retrieves an artifact by its ID, including its contents or a database preview.
```APIDOC
## Get Artifact
### Description
Get an artifact by ID with inline contents or database preview.
### Method
GET
### Endpoint
/artifacts/{artifact_id}
### Parameters
#### Path Parameters
- **artifact_id** (string) - Required - The unique identifier of the artifact.
### Response
#### Success Response (200)
- **artifact** (object) - Contains the artifact details, including its contents or preview.
```
--------------------------------
### List Skill Versions
Source: https://docs.hellofriday.ai/core-concepts/cli
List all available versions for a given skill. The skill name is required using the `-n` flag.
```bash
friday skill versions -n @tempest/pr-code-review
```
--------------------------------
### Get Environment Configuration
Source: https://docs.hellofriday.ai/api-reference/configuration/get-environment-config
Fetches the environment variables from the daemon's configuration.
```APIDOC
## GET /api/config/env
### Description
Get environment variables from the daemon's configuration.
### Method
GET
### Endpoint
/api/config/env
### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **envVars** (object) - An object containing key-value pairs of environment variables. The values are strings.
### Response Example
```json
{
"success": true,
"envVars": {
"VAR_NAME_1": "value1",
"VAR_NAME_2": "value2"
}
}
```
### Request Example
```bash
curl http://localhost:18080/api/config/env
```
```
--------------------------------
### Get Agent Details
Source: https://docs.hellofriday.ai/api-reference/agents/get-agent-details
Fetches detailed information about a specific agent by its ID.
```APIDOC
## GET /api/agents/{id}
### Description
Get detailed information about a specific agent.
### Method
GET
### Endpoint
/api/agents/{id}
### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent.
#### Response
##### Success Response (200)
- **id** (string) - The unique identifier of the agent.
- **name** (string) - The name of the agent.
- **description** (string) - A description of the agent.
- **type** (string) - The type of the agent.
#### Response Example
```json
{
"id": "slack",
"name": "Slack",
"description": "",
"type": ""
}
```
```
--------------------------------
### Configure Slack Credentials via .env File
Source: https://docs.hellofriday.ai/core-concepts/communicators/slack
For CI or scripted setups, store Slack API credentials in the `.env` file located in the Friday home directory. The `app_id` must still be provided in `workspace.yml`.
```bash
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=
```
```yaml
communicators:
slack:
kind: slack
app_id: A01234567
```
--------------------------------
### Real Example: Time Operations Agent
Source: https://docs.hellofriday.ai/sdk/python-reference/tools-capability
An agent demonstrating the use of time-related MCP tools. It configures a time server, lists available tools, calls the current time, and converts time between timezones.
```python
@agent(
id="time-agent",
version="1.0.0",
description="Time conversion",
mcp={
"time": {
"transport": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-time", "--local-timezone", "UTC"],
}
}
},
)
def execute(prompt, ctx):
# Discover available tools
tools = ctx.tools.list()
tool_names = [t.name for t in tools]
# Call current time
now = ctx.tools.call("get_current_time", {"timezone": "UTC"})
# Convert time
converted = ctx.tools.call(
"convert_time",
{
"source_timezone": "UTC",
"time": "14:30",
"target_timezone": "America/New_York",
},
)
return ok({
"current_utc": now,
"converted": converted,
"available_tools": tool_names,
})
```
--------------------------------
### Get Session Details
Source: https://docs.hellofriday.ai/api-reference/sessions/get-session
Fetches the details of a specific session by its unique identifier.
```APIDOC
## GET /api/sessions/{id}
### Description
Get details of a specific session.
### Method
GET
### Endpoint
/api/sessions/{id}
### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the session.
### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the session.
- **workspaceId** (string) - The identifier of the workspace the session belongs to.
- **status** (string) - The current status of the session (running, completed, failed, cancelled).
- **createdAt** (string) - The timestamp when the session was created.
- **completedAt** (string) - The timestamp when the session was completed.
#### Response Example
```json
{
"id": "sess-123",
"workspaceId": "ws-abc",
"status": "completed",
"createdAt": "2023-10-27T10:00:00Z",
"completedAt": "2023-10-27T10:05:00Z"
}
```
```
--------------------------------
### Setting Request Timeout
Source: https://docs.hellofriday.ai/sdk/python-reference/http-capability
Example of setting a custom timeout for an HTTP request.
```APIDOC
## Timeout
### Description
Example of setting a custom timeout for an HTTP request.
### Code
```python
response = ctx.http.fetch(
"https://slow-api.example.com/data",
timeout_ms=30000, # 30 seconds
)
```
```
--------------------------------
### Clone SDK Repository
Source: https://docs.hellofriday.ai/sdk/python
Clones the Friday agent SDK repository to your local machine. This is the first step in setting up the development environment.
```bash
git clone git@github.com:friday-platform/agent-sdk.git ~/agent-sdk
```
--------------------------------
### Tool Chaining for Sequential Operations
Source: https://docs.hellofriday.ai/sdk/python-reference/tools-capability
Chain multiple tool calls to perform a sequence of operations. This example demonstrates searching for issues, retrieving details of the top issue, and then adding a comment to it.
```python
def execute(prompt, ctx):
# Step 1: Search
search_result = ctx.tools.call(
"search_issues",
{"query": prompt},
)
# Step 2: Get details for top result
top_issue = search_result["issues"][0]
details = ctx.tools.call(
"get_issue",
{
"owner": "my-org",
"repo": "my-repo",
"issue_number": top_issue["number"],
},
)
# Step 3: Add comment
ctx.tools.call(
"add_issue_comment",
{
"owner": "my-org",
"repo": "my-repo",
"issue_number": top_issue["number"],
"body": "Analyzing this issue now...",
},
)
return ok({"analyzed": top_issue["title"]})
```
--------------------------------
### Get workspace status
Source: https://docs.hellofriday.ai/core-concepts/cli
Display the configuration and details for a specific workspace, identified by its name or ID.
```shell
friday workspace status -w my-space
```
--------------------------------
### Accessing Configuration
Source: https://docs.hellofriday.ai/sdk/python-reference/agent-context
Shows how to retrieve configuration values from the AgentContext. The .get() method is recommended for accessing optional configuration fields, providing default values if they are not set.
```python
platform_url = ctx.config.get("platformUrl", "http://localhost:18080")
skills = ctx.config.get("skills", [])
```
--------------------------------
### Passing Data Between Steps - outputTo and inputFrom
Source: https://docs.hellofriday.ai/core-concepts/jobs
Shows how to pass data between job steps using 'outputTo' to save a step's result and 'inputFrom' to use that result as input for a subsequent step.
```yaml
step-a:
entry:
- type: agent
agentId: agent-a
outputTo: step-a-result # saves output as named document
- type: emit
event: DONE
on:
DONE:
target: step-b
step-b:
entry:
- type: agent
agentId: agent-b
inputFrom: step-a-result # receives step-a's output as task input
- type: emit
event: DONE
```
--------------------------------
### Get Specific Friday Artifact
Source: https://docs.hellofriday.ai/core-concepts/cli
Retrieve a specific artifact by its ID. You can optionally specify a revision number.
```bash
friday artifacts get art_abc123
```
```bash
friday artifacts get art_abc123 --revision 2
```