Agnes AI

Agnes AI is an OpenAI-compatible platform offering language, image, and video generation models. UGENT integrates with all three Agnes capabilities through a single openai-compatible LLM instance.

Overview

Capability	Model	Endpoint
Chat / reasoning	agnes-2.5-flash	POST /v1/chat/completions
Image generation	agnes-image-2.1-flash	POST /v1/images/generations
Video generation	agnes-video-v2.0	POST /v1/videos (async)

Base URL: https://apihub.agnes-ai.com/v1

Agnes speaks the OpenAI Chat Completions protocol natively, so you configure it as an openai-compatible instance. UGENT auto-detects the Agnes endpoint and applies provider-specific handling for media transport (URL-only references, no base64 inline).

Quick Start

[llm]
default_instance = "agnes"

[llm.instances.agnes]
type = "openai-compatible"
base_url = "https://apihub.agnes-ai.com/v1"
api_key = "$AGNES_API_KEY"
default_model = "agnes-2.5-flash"
context_window = 512000
max_tokens = 65536
temperature = 0.7

Store your API key securely:

echo -n "your-agnes-api-key" | pbpaste | ugent secret add --stdin agnes_api_key

Then reference it from config with a vault handle:

[llm.instances.agnes]
api_key_ref = "@agnes_api_key"

Language Model: Agnes 2.5 Flash

agnes-2.5-flash is the flagship language model. It supports streaming, tool calling, image understanding (via image URLs), and a Thinking mode for coding and reasoning tasks.

Context Window and Output Limits

Parameter	Value
Context window	512,000 tokens
Maximum output	65,536 tokens

[llm.instances.agnes]
type = "openai-compatible"
base_url = "https://apihub.agnes-ai.com/v1"
api_key = "$AGNES_API_KEY"
default_model = "agnes-2.5-flash"
context_window = 512000
max_tokens = 65536

Reasoning (Thinking Mode)

Agnes 2.5 Flash supports a Thinking mode for coding, debugging, and multi-step agent workflows. UGENT enables this through the standard reasoning config:

[llm.instances.agnes]
# ... base config ...

[llm.instances.agnes.reasoning]
mode = "enabled"           # disabled | enabled | adaptive
effort = "medium"          # minimal | low | medium | high | xhigh | max

• mode = "enabled" — Thinking is always on. Use for complex coding, debugging, refactoring, and multi-step reasoning.
• mode = "adaptive" — UGENT activates Thinking when the task looks complex and skips it for simple queries to save tokens.
• mode = "disabled" — Thinking is off. Faster responses, lower token cost.

For complex debugging or multi-step agent workflows, increase effort to high or xhigh. For quick questions, minimal or low is sufficient.

Gray Release Note

agnes-2.5-flash is a gray-release model. If your API key is not in the gray-release group, fall back to agnes-2.0-flash (the stable predecessor):

default_model = "agnes-2.0-flash"

Both models share the same API contract, so only the model name changes.

Image Understanding

Agnes 2.5 Flash accepts image URLs in chat messages for visual question answering, screenshot analysis, and structured extraction:

[llm.instances.agnes]
# same config — image input is automatic when you attach an image

Ask questions about images directly in the chat. UGENT handles the multimodal message formatting automatically.

Image Generation: Agnes Image 2.1 Flash

agnes-image-2.1-flash supports text-to-image and image-to-image generation. Enable it under the instance's media generation config:

[llm.instances.agnes.media.generation.image]
enabled = true
model = "agnes-image-2.1-flash"
default_size = "2K"                    # 1K | 2K | 3K | 4K
response_format = "url"                # url | b64_json
max_images_per_request = 1

Size and Ratio

Use tier-based sizes (1K, 2K, 3K, 4K) combined with an aspect ratio. UGENT passes these through automatically.

Ratio	1K	2K	4K
1:1	1024x1024	2048x2048	4096x4096
16:9	1312x736	2624x1472	5248x2944
9:16	736x1312	1472x2624	2944x5248
4:3	1152x864	2304x1728	4608x3456
3:4	864x1152	1728x2304	3456x4608

Image-to-Image

Provide input image URLs. UGENT sends them in the extra_body.image array per the Agnes API contract. The generate_image tool handles this automatically when you attach reference images.

TIP

Agnes media transport is URL-only. Base64 inline encoding is disabled due to a server-side decoder issue. Use publicly accessible image URLs.

Video Generation: Agnes Video V2.0

agnes-video-v2.0 generates videos asynchronously. You create a task, then poll for the result. UGENT handles the polling lifecycle automatically and downloads the video to the media store on completion.

[llm.instances.agnes.media.generation.video]
enabled = true
model = "agnes-video-v2.0"
default_width = 1152
default_height = 768
default_num_frames = 121          # must satisfy 8n+1 (81, 121, 241, 441)
default_frame_rate = 24           # 1-60 FPS
max_poll_duration_secs = 600      # hard timeout for background polling

Video Modes

Mode	Description
Text-to-video	Generate from a text prompt only
Image-to-video	Animate a static image
Keyframe animation	Smooth transition between multiple keyframe images

Duration Control

Video duration is determined by frame count and frame rate:

seconds = num_frames / frame_rate

Duration	num_frames	frame_rate
~3 seconds	81	24
~5 seconds	121	24
~10 seconds	241	24
~18 seconds	441	24

Frame Count Rule

num_frames must follow the 8n + 1 rule. Valid values: 9, 17, 25, 33, ..., 81, 121, 161, 241, 441 (maximum).

Resolution

The model normalizes requests to three tiers: 480p, 720p, and 1080p. Supported aspect ratios: 16:9, 9:16, 1:1, 4:3, 3:4. UGENT passes your requested dimensions and the API maps to the nearest preset.

Complete Configuration Example

[llm]
default_instance = "agnes"

[llm.instances.agnes]
type = "openai-compatible"
base_url = "https://apihub.agnes-ai.com/v1"
api_key_ref = "@agnes_api_key"
default_model = "agnes-2.5-flash"
context_window = 512000
max_tokens = 65536
temperature = 0.7

[llm.instances.agnes.reasoning]
mode = "enabled"
effort = "medium"

# Image generation
[llm.instances.agnes.media.generation.image]
enabled = true
model = "agnes-image-2.1-flash"
default_size = "2K"
response_format = "url"
max_images_per_request = 1

# Video generation
[llm.instances.agnes.media.generation.video]
enabled = true
model = "agnes-video-v2.0"
default_width = 1152
default_height = 768
default_num_frames = 121
default_frame_rate = 24
max_poll_duration_secs = 600

Using Agnes with Other Providers

You can run Agnes alongside other providers and route between them:

[llm]
default_instance = "agnes"

[llm.instances.agnes]
type = "openai-compatible"
base_url = "https://apihub.agnes-ai.com/v1"
api_key_ref = "@agnes_api_key"
default_model = "agnes-2.5-flash"
context_window = 512000
max_tokens = 65536

[llm.instances.opus]
type = "anthropic"
api_key_ref = "@anthropic_api_key"
default_model = "claude-opus-4-8"
context_window = 200000
max_tokens = 200000

[llm.instances.gemini]
type = "google"
api_key_ref = "@google_api_key"
default_model = "gemini-3.5-pro"
context_window = 1000000
max_tokens = 65536

Switch between providers at runtime with /model agnes or /model opus.

Delegating Media Generation to Agnes

A text-capable model (Claude, GPT, Gemini) can dispatch a sub-agent that runs on the Agnes instance to generate images or videos. The sub-agent inherits Agnes's media generation tools — generate_image, generate_video, and check_video — because tools are registered per-instance based on the media.generation config.

The orchestrator does this through the delegate_task tool with provider_target set to the Agnes instance:

provider_target: "openai-compatible:agnes"

The format is {provider_type}:{instance_name}. The main model stays on its reasoning provider while the delegated sub-agent handles media generation on Agnes. Results (image file paths, video task IDs) are returned to the parent.

This pattern is ideal when:

• Your primary model excels at reasoning but cannot generate images or video
• You want to keep the conversation on one model while offloading media tasks
• You need different media backends for different tasks (Agnes for images, Google Veo for video, Seedance for advanced video)

Pricing

Agnes models are currently in a promotional period (as of July 2026):

Model	Standard Price	Current Price
Agnes 2.5 Flash (input)	$0.03 / 1M tokens	Free
Agnes 2.5 Flash (output)	$0.15 / 1M tokens	Free
Agnes Image 2.1 Flash	$0.003 / image	Free
Agnes Video V2.0	$0.005 / second	Free

Check the Agnes AI pricing page for the latest rates.