Quickstart

The goal is to get one minimal end-to-end request running, then point you at the right next step.

Install

pip install -U agently

uv pip install -U agently works the same way.

Configure a model

Agently ships three protocol-level request plugins: OpenAICompatible (Chat Completions compatible endpoints), OpenAIResponsesCompatible (Responses API shape), and AnthropicCompatible (Claude / Anthropic Messages API). Pick the one that matches the endpoint you are pointing at.

from agently import Agently

Agently.set_settings(
    "OpenAICompatible",
    {
        "base_url": "https://api.openai.com/v1",
        "api_key": "${ENV.OPENAI_API_KEY}",
        "model": "${ENV.OPENAI_MODEL}",
    },
)

For Claude:

Agently.set_settings(
    "AnthropicCompatible",
    {
        "base_url": "https://api.anthropic.com",
        "api_key": "${ENV.ANTHROPIC_API_KEY}",
        "model": "${ENV.ANTHROPIC_MODEL}",
        "max_tokens": 4096,
    },
)

For Ollama or any other OpenAI-compatible local server, set base_url to that server (for Ollama: http://127.0.0.1:11434/v1) and set model to the local model name. api_key can be omitted for local-only setups that don't require it.

See Model Setup for the full provider list and ${ENV.*} placeholders.

Run one structured request

from agently import Agently

agent = Agently.create_agent()

result = (
    agent
    .input("Write a one-line positioning statement and two highlights for Agently.")
    .output({
        "positioning": (str, "One-line positioning", True),
        "highlights": [
            {
                "title": (str, "Highlight title", True),
                "detail": (str, "One-line detail", True),
            }
        ],
    })
    .start()
)

print(result)

Each leaf is (type, description, ensure). The third slot is the ensure flag — set to True to guarantee the field is present in the parsed result, retrying the request if needed. See Schema as Prompt.

Core creation styles

Agently supports both direct constructors and factory helpers for first-class core instances:

from agently import Agent, Agently, TriggerFlow

agent = Agent("repo-worker")
factory_agent = Agently.create_agent("repo-worker")

flow = TriggerFlow(name="review-flow")
factory_flow = Agently.create_trigger_flow("review-flow")

workspace = Agently.create_workspace("./.agently/runs/review-flow")

What to read next

• Building a service, streaming UI, or workflow → Async First
• More providers and env-driven settings → Model Setup
• Stronger output guarantees and validation → Output Control
• Reading text, data, and metadata from one response → Model Response
• Project layout for non-trivial apps → Project Framework
• Branching, loops, pause/resume → TriggerFlow Overview

Common pitfalls

• Building a custom JSON parser before trying output().
• Jumping into TriggerFlow before getting a single request right.
• Mixing prompt definition, settings, and business logic in one script — see Project Framework.