Quickstart

This page is for first-time Agently users. Run the core flows in 5 minutes.

1. Install

Agently is published on PyPI. Install with pip:

pip install -U Agently

If you use uv or pipx, install from PyPI with:

uv pip install -U Agently

pipx install Agently
pipx upgrade Agently

2. Model setup

Before your first run, set a model. Agently v4 uses OpenAICompatible. For English developers, you can use the OpenAI official API for testing.

from agently import Agently

Agently.set_settings("OpenAICompatible", {
  "base_url": "https://api.openai.com/v1",
  "api_key": "YOUR_OPENAI_API_KEY",
  "model": "gpt-4o-mini"
})

For common providers, see Common Model Settings.

3. Basic input/output (structured)

Shortest path: input() → output() → start(). This example uses a nested Output Format.

from agently import Agently

agent = Agently.create_agent()

result = (
  agent
  .input("Write a short intro for Agently with a one-line positioning and 2 key highlights")
  .output({
    "Positioning": ("str", "One-line positioning"),
    "Highlights": [
      {
        "Title": ("str", "Highlight title"),
        "Detail": ("str", "One-line detail")
      }
    ]
  })
  .start()
)

print(result)

Example output:

{
  "Positioning": "A production-ready AI application framework",
  "Highlights": [
    { "Title": "Structured output", "Detail": "Verifiable and portable contracts" },
    { "Title": "Event orchestration", "Detail": "Controllable, reproducible flows" }
  ]
}

4. Async usage

Agently provides async API, ideal for concurrency or web services.

import asyncio
from agently import Agently

agent = Agently.create_agent()

async def main():
  result = await (
    agent
    .input("List three delivery challenges for AI apps")
    .output(["str"])
    .async_start()
  )
  print(result)

asyncio.run(main())

Example output:

['Uncontrolled outputs', 'Hard-to-reproduce flows', 'High ops cost']

5. Instant structured streaming

Instant mode streams structured output while generating.

from agently import Agently

agent = Agently.create_agent()

response = (
  agent
  .input("Explain recursion in one sentence, and give 2 tips")
  .output({
    "definition": ("str", "Short definition"),
    "tips": [("str", "Short tip")]
  })
  .get_response()
)

for msg in response.get_generator(type="instant"):
  if msg.path == "definition" and msg.delta:
    print(msg.delta, end="", flush=True)
  if msg.wildcard_path == "tips[*]" and msg.delta:
    print(msg.delta, end="", flush=True)
print()

Streaming output (sample):

Recursion is a function calling itself.
Tip 1: Define a clear termination condition.
Tip 2: Ensure the problem size shrinks.

Next

• Model output control & Agently Output Format
• Prompt management for production
• TriggerFlow event orchestration
• Config-first prompt management and model hot-swap