Skip to main content

sofias-sdk-lite

Build multi-node agents on a declarative graph and run them against RabbitMQ.

Documentation: docs.sofias.ai · Developer portal: developers.sofias.ai · Source: github.com/Sofias-ai/sofias-sdk-lite

sofias-sdk-lite gives you:

  • An agent graph — LLM nodes, function nodes, delegation nodes (agent-to-agent), aggregator nodes (fan-in), and planner nodes (dynamic DAGs), wired together with explicit routing strategies.
  • A messaging layer — pydantic wire models (AgentTaskMessage, StreamFragment, delegation contracts) and a RabbitMQ transport (client, consumer, publisher, RPC, delegation transport) built on aio-pika and RabbitMQ Streams.
  • A runner — AgentRunner consumes tasks from a queue, resolves per-request settings, executes your agent, and streams the response back — with graceful shutdown, retries, and circuit breakers built in.
  • An LLM that is already wired — LLM nodes talk to the Sofias gateway (or any OpenAI-compatible endpoint) using the model, URL and key from the agent's settings or the SOFIAS_LLM_* environment. create_llm() builds the client when you need it explicitly; LLMCallable stays a protocol for anything the bundled clients do not cover.
  • The user's connectors — McpToolProvider turns the connectors the platform sends with each turn (mail, documents, CRM, the company's own MCP servers…) into tools for your LLM nodes. They go through the platform's intermediary: your agent never sees a credential. See Using the user's connectors.

Nothing here depends on a private backend or an internal config service. Where the model lives is deployment configuration, not agent code.

Install

pip install sofias-sdk-lite
# or
uv add sofias-sdk-lite

Requires Python 3.11+ and a running RabbitMQ broker (with the Streams plugin enabled) if you use the runner or streaming responses.

Quickstart

A minimal agent with a single function node:

import asyncio

from sofias_sdk_lite import (
    AgentBuilder,
    AgentMessage,
    BaseAgentSettings,
    InputContract,
    NodeContract,
    OutputContract,
)


class GreetInput(InputContract):
    name: str


class GreetOutput(OutputContract):
    greeting: str


class HelloSettings(BaseAgentSettings):
    pass


def greet(data: dict, context: dict | None = None) -> dict:
    return {"greeting": f"Hello, {data['name']}!"}


async def main() -> None:
    contract = NodeContract(input_schema=GreetInput, output_schema=GreetOutput)
    agent = (
        AgentBuilder("hello_agent", version="0.1.0")
        .with_settings_class(HelloSettings)
        .with_contract(input_schema=GreetInput, output_schema=GreetOutput)
        .add_function_node("greeter", contract, process_fn=greet)
        .set_entry_node("greeter")
        .set_terminal("greeter")
        .build()
    )

    response = await agent.execute(AgentMessage(content=GreetInput(name="World")))
    print(response.content)  # {"greeting": "Hello, World!"}


asyncio.run(main())

See examples/ for a runner against a local RabbitMQ (docker-compose.yml included), tool loops, streaming, and agent-to-agent delegation.

Connecting to the LLM

An agent declares what the model should do; where the model lives is resolved at build():

  1. Under AgentRunner, from the per-task settings the platform sends (model_name, router_url, router_api_key on BaseAgentSettings).
  2. Otherwise from the environment: SOFIAS_LLM_MODEL, SOFIAS_LLM_BASE_URL, SOFIAS_LLM_API_KEY and SOFIAS_LLM_PROVIDER (default sofias). The Sofias platform injects them into every agent it runs, so an agent deployed through the developer portal needs no LLM configuration at all. There is no default URL: to run locally against a real gateway, set it.
  3. Or explicitly: .with_llm(create_llm(model="default", api_key=...)).
from sofias_sdk_lite import (
    AgentBuilder, LLMNodeConfig, NodeContract, NodePromptConfig,
)

agent = (
    AgentBuilder("qa_agent")
    .with_settings_class(MySettings)
    .with_contract(input_schema=Question, output_schema=Answer)
    .add_llm_node(
        "answerer",
        LLMNodeConfig(name="answerer", input_contract=Question, output_contract=Answer,
                      # {question} is Question.question — this is how the input
                      # reaches the model. Without it the model answers blind.
                      prompt=NodePromptConfig(prompt="Answer this: {question}"),
                      system_prompt="Answer in one sentence."),
        NodeContract(input_schema=Question, output_schema=Answer),
    )
    .set_entry_node("answerer")
    .set_terminal("answerer")
    .build()          # no LLM client anywhere in this file
)

prompt is how the node's input reaches the model. The input is substituted into the {placeholders} of NodePromptConfig and nowhere else: there is no separate "user message" channel, and system_prompt does not carry it — that one is standing instruction (how to answer), not the task. Name every input field the model needs to see.

A node with no prompt at all still works: the SDK appends the input as a JSON ## Input section so nothing is silently lost. But the template is what gives you control over how the model reads the task, so write it.

See examples/03_llm_agent.py and the LLM integration guide (prompts, streaming, retries, bringing your own client).

Running an agent against RabbitMQ

from sofias_sdk_lite import AgentRunner, RunnerConfig, RabbitMQConfig, AgentMessage


class MyAgentRunner(AgentRunner):
    settings_class = MySettings

    def build_agent(self, settings, workflow):
        return (
            AgentBuilder("my_agent")
            .with_settings_class(type(settings))
            .with_response_workflow(workflow)
            # ... nodes, routing ...
            .build()
        )

    def prepare_input(self, task, history, role):
        return AgentMessage(
            content=MyInput(message=task.content, role=role),
            conversation_id=task.conversation_id,
        )


if __name__ == "__main__":
    MyAgentRunner(
        RunnerConfig(
            queue="my-agent-tasks",
            agent_name="my_agent",
            rabbitmq=RabbitMQConfig(host="localhost"),
        )
    ).run()

Optional extras

  • sofias-sdk-lite[otel] — installs opentelemetry-api so the runner opens an agent.handle span per turn and response fragments carry the active span's traceparent. Without it, the inbound traceparent is still echoed end to end.

Scope (v1)

Core agent graph, RabbitMQ messaging, the runner, LLM clients for the Sofias gateway / any OpenAI-compatible endpoint and, since 0.3.0, the user's connectors (MCP) ship today. Memory is intentionally out of scope for v1 — the SDK ships the MemoryProvider protocol so you can plug in your own, and it becomes an optional extra in a later release.

Source and contributions

The public repository holds read-only release snapshots: each release of sofias-sdk-lite appears there as a single commit. Development happens elsewhere, so pull requests cannot be merged and we do not accept contributions at the moment. For questions or to report a problem, write to support@sofias.ai.

License

Source-available under the Sofias SDK Lite License: you may use sofias-sdk-lite to develop, test and run agents for the Sofias platform. The agents you build with it are yours.

Metadata

Release files for sofias-sdk-lite 0.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sofias-sdk-lite 0.4.2
File Size Uploaded Provenance Actions
sofias_sdk_lite-0.4.2.tar.gz 163.5 kB Without provenance Details for sofias_sdk_lite-0.4.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sofias-sdk-lite 0.4.2
File Interpreter ABI Platform Actions
sofias_sdk_lite-0.4.2-py3-none-any.whl Python 3 none any Details for sofias_sdk_lite-0.4.2-py3-none-any.whl

Total release size: 366.7 kB

Release files / sofias_sdk_lite-0.4.2.tar.gz

Download URL sofias_sdk_lite-0.4.2.tar.gz
Size 163.5 kB
Tags Source
SHA-256 checksum
How to use checksums
8731cd07d18df303055c1150fe44e87eccf5447643dad28d49e1ae80a02e3c67
BLAKE2b-256 checksum
How to use checksums
89bda54fb5d8d81929eeb9b1c55812098a0fbb4cbde17ecbc011c4a5d541d5b7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Wolfi","version":"20230201","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / sofias_sdk_lite-0.4.2-py3-none-any.whl

Download URL sofias_sdk_lite-0.4.2-py3-none-any.whl
Size 203.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fb5cbf4a6463aeb300db84a837d8879b8c463c737b12d60667b80fd681456367
BLAKE2b-256 checksum
How to use checksums
d3ab619432bb95f6782bac583cb473bf1f9b04325b7cbe30e1a7b513522668f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Wolfi","version":"20230201","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for sofias-sdk-lite 0.4.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page