What you can build with Fred

Three ways to add your business logic to the platform.

Start with the user’s task, then choose what you need to build.

The main parts of Fred

A pod is a service you run; it can start locally as a Python process.

Your agent executes in its pod. Knowledge Flow manages the documents.

What happens when you send a message?

A managed agent instance is an agent configured for one team.

The Control Plane prepares the request. The runtime checks access and executes it.

Your code, Fred’s responsibilities

Begin with the SDK; learn the infrastructure as your application needs it.

Underneath: fred-pod handles configuration and workload identity;
fred-core provides shared infrastructure for agents and platform services.

You own business behavior. Fred supplies the execution and integration framework.

An agent starts with a Python definition

A minimal equivalent of the sample assistant, using the SDK authoring API.

from fred_sdk import ReActAgent

class Assistant(ReActAgent):
    agent_id: str = "fred.samples.assistant"
    role: str = "General-purpose assistant"
    description: str = "Answers general questions."
    system_prompt_template: str = (
        "Answer clearly. Say when you are uncertain."
    )

agent = Assistant()
REGISTRY = {agent.agent_id: agent}

This first agent needs a configured model, with no external tools.

Run the sample pod locally

The app factory exposes your registry as an HTTP service.

from fred_runtime.app import (
    create_agent_app,
    load_agent_pod_config,
)
from fred_samples_agents.registry import REGISTRY

app = create_agent_app(
    registry=REGISTRY,
    config=load_agent_pod_config(),
)

cd ~/Fred/fred-samples/agents
cp -n config/env.template config/.env
# Set OPENAI_API_KEY to your Mistral key
make run

You can try the assistant before connecting the pod to the Fred UI.

Talk to the agent over HTTP

The CLI is a client of the same runtime API. Keep the pod running in another terminal.

make cli

/agents
/agent fred.samples.assistant
Explain what an API is.

curl -N \
  http://127.0.0.1:8010/samples/agents/v1/agents/execute/stream \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "fred.samples.assistant",
    "input": "Explain what an API is.",
    "session_id": "demo-01",
    "runtime_context": {"user_id": "demo"}
  }'

Direct agent IDs are useful for local tests; the Fred UI uses managed instances.

Make the agent available to a team

The Python definition becomes a discoverable template; a team enrolls an instance.

One agent definition can serve multiple configured team instances.

A Python function becomes an agent tool

The model chooses when to call it. Python performs the conversion.

from fred_sdk import ReActAgent, ToolContext, ToolOutput, tool

@tool("acme.units.to_metres", description="Convert km to metres.")
async def to_metres(ctx: ToolContext, km: float) -> ToolOutput:
    return ctx.text(f"{km * 1000:g} metres")

class UnitsAgent(ReActAgent):
    agent_id: str = "acme.units.assistant"
    role: str = "Unit conversion assistant"
    description: str = "Converts distances using a Python tool."
    system_prompt_template: str = "Use the tool for conversions."
    tools = (to_metres,)

agent = UnitsAgent()
REGISTRY = {agent.agent_id: agent}

You write the function and instructions. Fred runs the tool-calling loop.

Call a service through MCP

MCP is a protocol for discovering tools and invoking them across a service boundary.

# Inside the BankTransferGraphAgent definition:
default_mcp_servers: tuple[MCPServerRef, ...] = (
    MCPServerRef(id="mcp-bank-core-demo"),
    MCPServerRef(id="mcp-risk-guard-demo"),
)

A local @tool runs in the agent pod. An MCP tool runs in a separate service.

Keep the same tool concept while choosing where the implementation runs.

Use a graph to define the workflow

ReAct lets the model choose tool calls. A graph defines the allowed steps and transitions.

workflow = GraphWorkflow(
    entry="classify",
    nodes={
        "classify": classify_step,
        "greet": greet_step,
        "answer": answer_step,
        "finalize": finalize_step,
    },
    edges={"greet": "finalize", "answer": "finalize"},
    routes={"classify": {
        "greeting": "greet",
        "question": "answer",
    }},
)

You control the workflow; individual steps can still use a model.

Pause before committing an action

Human-in-the-loop (HITL) makes a user decision part of the workflow.

choice_id = await choice_step(
    context,
    stage="transfer_confirmation",
    title="Confirm Transfer",
    question=question,
    choices=[
        HumanChoiceOption(id="confirm", label="Confirm"),
        HumanChoiceOption(id="cancel", label="Cancel"),
    ],
)
return StepResult(
    route_key="confirmed" if choice_id == "confirm"
    else "cancelled"
)

The bank sample also asks for risk approval when the risk is elevated.

One business API, two ways to use it

A person uses your interface. An agent calls your MCP tools. Your service owns the records.

Example: progress-tracker — FastAPI + SQLite + an MCP endpoint.
* Both API paths check the user’s identity and team access; the iframe receives no Fred token.

Keep business rules in your API, shared by the interface and the agent tools.

Connect your interface to Fred

The iframe SDK lets your page ask its host for context, navigation and API requests.

import { createFredApplicationClient }
  from "@fred-oss/iframe-sdk";

const fred = createFredApplicationClient({
  hostOrigin: "https://fred.example",
  applicationId: "progress-tracker",
});
await fred.connect();

const response = await fred.request("tasks");
if (!response.ok) throw new Error("Request failed");
const tasks = await response.json();

The host handles Fred credentials. Your iframe receives context and API responses.

Expose your business API as MCP tools

The current samples keep the interface, API and tools around the same service.

# Progress Tracker: the same API serves both entry points
REST: /teams/{team_id}/tasks
MCP:  /mcp

Application grant: app__progress-tracker
MCP capability:    mcp-progress-tracker

The API validates the caller and team access for both people and agents.

Choose who owns the durable record

The two sample applications make different choices about writes and storage.

A third sample, Review Board, adds a staged agent workflow and application-owned OpenSearch.

Choose the write and storage model before implementing the interface.

Knowledge Flow and Knowledge Bases

One service manages the documents; a connector keeps their source in sync.

Examples: a local folder, a Git repository or a WebDAV share. Knowledge Base authoring is currently beta.

The connector supplies documents. Knowledge Flow makes them available for retrieval.

How documents become useful to an agent

Ingestion happens when content changes. Retrieval happens when a question needs it.

Retrieval supplies context to the model; it does not train the model on your documents.

Publish a document through the SDK

Inside a synchronization handler, write to the library assigned to the run.

async with DocumentPublisher(
    PodConfiguration.load(),
    library_id=context.library_id,
    source_tag="fred",
) as publisher:
    handle = await publisher.publish(
        relative_path="handbook.md",
        content=b"# Handbook\nWelcome to the team.",
        version="v1",
    )
    outcome = await publisher.wait(handle.task_id)
    if not outcome.succeeded:
        raise RuntimeError("Document ingestion failed")

A successful upload is not yet proof that ingestion has completed.

Start with the local-folder sample

Understand the synchronization loop before connecting a remote source.

cd ~/Fred/fred-samples/knowledge-bases/local-folder
make declaration
CONFIG_FILE=/nonexistent ENV_FILE=/nonexistent \
  make sync ROOT=/path/to/notes

Keep source synchronization reliable; let Knowledge Flow own document processing.

Two local modes, two purposes

Both run the same infrastructure: Keycloak, PostgreSQL, OpenSearch, OpenFGA, Temporal and S3 storage.

Run one mode at a time: both use the same host ports.

Debug in Docker; prove it in k3d before you ship.

Docker: the fast debug loop

The infrastructure runs in containers; Fred and your pods run as local processes.

# fred-deployment-factory: the infrastructure
make docker-up

# fred: the four Fred services
make setup-env    # once: .env files, model key
make run          # Ctrl+C stops all four

Use Docker to find the bug; it is not a deployment.

k3d: the platform as production runs it

Every application is deployed with its own Helm chart, in a local Kubernetes cluster.

• Same chart and posture as production: security profile, delegation, migration Jobs, credentials read from one Secret.
• Images are tagged by content: rerun after any change and only what changed rolls out.
• Examples: ../fred-agent-evaluator, ../fred-samples/knowledge-bases/webdav.

What works on k3d has met the real chart, identities and permissions.

Make your application deployable on k3d

Your repository carries its own deployment; the factory names no application.

helmfile.yaml.gotmpl  your releases: chart + values
values.yaml           what k3d decides
identities.yaml       your service clients
build                 your images
prepare, finish       before and after the sync

clients:
  - id: my-app-worker
    secret: MY_APP_CLIENT_SECRET
    grants: [app/service_agent]

You declare what your application needs; the platform decides how to provide it.

Find what went wrong

The k3d stack collects every pod's logs, the Kubernetes events, metrics and workflows.

make k3d-health
bin/k3d-observe trace <id>
bin/k3d-observe logs '<query>'
bin/k3d-observe kpi

Read the collected evidence before reading pod consoles.