Agentica is a type-safe AI framework that lets LLM agents integrate with your code—functions, classes, live objects, even entire SDKs. Instead of building MCP wrappers or brittle schemas, you pass references directly; the framework enforces your types at runtime, constrains return types, and manages agent lifecycle.

This repository contains the session management backend (the "server"). It handles session orchestration, state persistence, sandboxed code execution, and coordination between clients and the Agentica runtime.

The full documentation for the SDKs can be found at docs.symbolica.ai.

At present, building and running the server requires one of the following platforms

• macOS (arm64, x86_64)
• Linux (x86_64, aarch64)

and the presence of the following tools

• uv
• curl, tar, shasum, bash

uv sync

The most common configuration for usage will be

export OPENROUTER_API_KEY="your-api-key"
uv run agentica-server

While for development of the server itself we suggest

export OPENROUTER_API_KEY="your-api-key"
export AGENTICA_LOG_TAGS=CORE
uv run agentica-server --log-level=INFO

The server starts on port 2345 by default. Use --port to change this.

To see all available options:

uv run agentica-server --help

By default, the server uses https://openrouter.ai/api as the base URL and environment variable OPENROUTER_API_KEY as the api key.

You can configure multiple inference providers to route different models to different endpoints. This is useful for:

• Using OpenAI's native API for OpenAI models (better performance, access to latest features)
• Routing specific models to specific providers
• Using different API keys for different model families

Create a inference_providers.yml file:

# First matching provider wins (order matters)
- endpoint: https://api.openai.com/v1/responses
  token: ${oc.env:OPENAI_API_KEY}
  model_pattern: "openai/*"

- endpoint: https://openrouter.ai/api/v1/chat/completions
  token: ${oc.env:OPENROUTER_API_KEY}
  # model_pattern defaults to "*" (matches all)

Then run:

uv run agentica-server --inference-providers inference_providers.yml

The ${oc.env:VAR_NAME} syntax reads environment variables at startup.

For backward compatibility, you can still use the legacy CLI arguments:

uv run agentica-server \
  --inference-endpoint https://openrouter.ai/api/v1/chat/completions \
  --inference-token $OPENROUTER_API_KEY

This creates a single provider that matches all models.

Please report bugs, feature requests, and other issues in the symbolica-ai/agentica-server repository.

This project is licensed under the MIT License.