Building Agents with the Swiss AI Hub SDK

An agent in the Swiss AI Hub is a workflow defined by a series of steps that process events. Agents can interact with users, call external services, and coordinate with other agents to perform complex tasks.

This documentation guides you through the architecture, patterns, and best practices for building robust and scalable agents.

WARNING

Before you begin, please complete the Development Environment Setup and build Your First Agent.

What's Covered

This guide is structured to build your knowledge progressively:

1. Agent Fundamentals - The core architecture, including events, steps, and configuration.
2. Core Patterns - Essential workflow patterns like conditional logic, loops, and state management.
3. Human in the Loop - Building interactive workflows that require human approval or input.
4. Multi-Agent Systems - Coordinating multiple agents to solve complex problems.
5. Memory - Adding persistent memory to your agents for user preferences and organizational knowledge.
6. Testing and Debugging - Best practices for ensuring your agent is reliable and correct.
7. Production Deployment - Guidelines for packaging and deploying your agent.
8. Agent Observation - Monitoring your agent's behavior and performance with integrated tracing.
9. Configurable Agent Forms - Making agent configuration editable through the Admin UI using the Form Duality Pattern.
10. Execution Model - How the dispatcher executes steps, synchronization primitives, anti-patterns, and troubleshooting.
11. Events Reference - Complete event hierarchy, choosing the right base event, and available events catalog.
12. Using MCP Tools - Connecting agents to external MCP servers to call their tools.

Key Principles of the SDK

The SDK is designed around a few core principles to make development intuitive and scalable:

• Event-Driven by Nature: Agents react to a stream of events. This asynchronous, message-based architecture makes workflows dynamic and resilient.
• Declarative Workflows: You define what each step does using the @step decorator. The SDK automatically handles the how of routing events and wiring your steps together.
• Managed State: Handle conversation memory and run-time data effortlessly with injectable RunContext and ThreadContext objects, backed by a distributed store.
• Built for Production: With strongly-typed configuration, a dedicated testing framework, and built-in observability.

The Development Workflow

Building a high-quality agent typically follows these four stages:

TIP

A core design principle is that each agent should do one thing well. Complex problems are best solved by coordinating multiple specialized agents.

1. Design Your Workflow: Outline your agent's purpose, the events it will handle, and the sequence of steps it will take to achieve its goal.
2. Implement the Core Logic: Write your Agent class, define its strongly-typed AgentConfig, and implement the @step methods that transform events.
3. Test and Debug: Use the AgentTestRunner for unit testing and a tracing tool like Langfuse to visually debug the flow of events through your agent.
4. Deploy and Monitor: Package your agent and deploy it to the Swiss AI Hub, where its performance and behavior can be monitored in real-time.

Next Steps

Start with agent fundamentals to understand the core architecture, then explore the specific patterns and techniques in the following sections.