fred-sdk 0.1.6

Authoring SDK for Fred agents — graph, ReAct, and team agent primitives.

Fred SDK

fred-sdk is the authoring SDK for Fred agents. It provides the public APIs and abstractions required to define agents, workflows, and multi-agent compositions without depending on platform-specific runtime internals.

It is intended to be used together with fred-runtime, which provides the execution layer used to run those agents inside an application.

---

Overview

The Fred architecture separates agent definition from agent execution.

This separation is reflected in two complementary API layers:

1. Authoring APIs (fred-sdk)

These APIs are used to define agents declaratively.

They cover concerns such as:

• agent identity and metadata
• prompts and policies
• tool declarations
• workflow structure
• team and multi-agent composition
• human-in-the-loop patterns
• abstract runtime contracts

This is the layer used by agent authors.

2. Runtime APIs (fred-runtime)

These APIs are used to execute agents inside a real application environment.

They cover concerns such as:

• application creation
• registry wiring
• runtime configuration
• checkpointing
• tracing and observability
• security integration
• infrastructure adapters

This is the layer used by application and platform developers.

In summary:

• fred-sdk defines the agent
• fred-runtime runs the agent

---

What fred-sdk is for

Developers use fred-sdk to build Fred agents in a portable and structured way.

It supports several paradigms, including:

• ReAct-style agents
• graph-based workflows
• team and multi-agent systems
• human-in-the-loop workflows

The goal is to let developers focus on behavior and orchestration without wiring runtime infrastructure directly into agent definitions.

---

Installation

pip install fred-sdk

---

Quickstart

A realistic minimal example is to declare an agent with fred-sdk, then run it through an application created with fred-runtime.

Agent definition with fred-sdk

from fred_sdk.contracts.models import ReActAgentDefinition, ReActPolicy


class GeneralAssistantDefinition(ReActAgentDefinition):
    agent_id: str = "fred.samples.assistant"
    role: str = "General-purpose assistant"
    description: str = (
        "A helpful, concise assistant for general questions and conversation. "
        "No external tools or document retrieval required."
    )
    tags: tuple[str, ...] = ("general", "react")
    system_prompt_template: str = """\
You are a helpful, knowledgeable, and concise assistant.
Answer questions clearly and directly. When you are uncertain, say so.
You have no access to external tools or documents — work only from your own knowledge.
"""

    def policy(self) -> ReActPolicy:
        return ReActPolicy(system_prompt_template=self.system_prompt_template)


GENERAL_ASSISTANT_AGENT = GeneralAssistantDefinition()

This example illustrates the authoring API: the agent is defined declaratively through a public SDK model.

Application startup with fred-runtime

from fastapi import FastAPI
from fred_runtime.app import AgentPodConfig, create_agent_app, load_agent_pod_config

from fred_samples_agents.registry import REGISTRY


def create_app(config: AgentPodConfig | None = None) -> FastAPI:
    resolved_config = config if config is not None else load_agent_pod_config()
    return create_agent_app(registry=REGISTRY, config=resolved_config)


app = create_app()

This example illustrates the runtime API: the registry and configuration are assembled into an executable FastAPI application.

---

Understanding the two API levels

The distinction between the two layers is intentional.

In fred-sdk, developers declare agents

For example, an agent author defines:

• the agent identifier
• the role and description
• the system prompt
• the policy
• optional tool and workflow contracts

This code should remain portable and mostly independent from deployment concerns.

In fred-runtime, developers run agents

For example, an application developer or platform team:

• creates an agent registry
• loads runtime configuration
• wires checkpointing and runtime services
• exposes the agents through an application

This code is responsible for effective execution.

---

Relationship with fred-runtime

fred-sdk and fred-runtime are designed to be used together, with a clean separation of responsibilities.

• fred-sdk provides the public authoring surface
• fred-runtime provides the execution environment

Behind the scenes, Fred uses LangChain and LangGraph for orchestration and runtime behavior, but these concerns are intentionally separated from the authoring layer as much as possible.

---

Design principles

• Separation of concerns: authoring and runtime are distinct layers
• Portability: agent definitions should not depend on a specific backend
• Composability: simple agents, workflows, and team agents should share a coherent model
• Extensibility: runtime implementations can evolve without changing the authoring model
• Clarity: public APIs for agent authors should remain stable and easy to understand

---

Notes

• fred-sdk depends on fred-core and fred-portable, which are installed automatically
• The public SDK surface is exposed through fred_sdk/__init__.py for convenient top-level imports
• Runtime-specific application bootstrapping belongs in fred-runtime, not in fred-sdk

---

Resources

• Homepage: https://fredk8.dev
• Repository: https://github.com/ThalesGroup/fred
• Runtime package: https://pypi.org/project/fred-runtime/

---

Conceptual model

• fred-sdk: authoring APIs used to define agents
• fred-runtime: runtime APIs used to execute them