Agentic Functions

This is detailed usage documentation. New to the Agentica SDK? Start with the Quickstart or learn when to use agentic functions vs agents.

Using agentic

Agentic functions are stateless, decorator‑based functions implemented by the model; each call is independent. The de facto way to implement an agentic function is via the @agentic decorator.

When to use agentic functions

Agentic functions work best for completing simple, well-defined tasks that don’t benefit from maintaining context across multiple operations. For longer-running, multi-task, contextual problem solving, see Agents.

The basics

The Agentica SDK’s agentic decorator enables you to turn regular Python or TypeScript functions into agent-backed functions. Define a function with a descriptive prompt or docstring and simply call it like any other function.

Function bodies in Python should contain a descriptive doc-string, but otherwise be empty (body contains ...). See here for best practices on writing effective doc-strings.

from agentica import agentic

@agentic()
async def rhymes(word_a: str, word_b: str) -> bool:
    """
    Returns whether `word_a` rhymes with `word_b`.
    """
    ...

import { agentic } from '@symbolica/agentica';

async function rhymes(wordA: string, wordB: string): Promise<boolean> {
  return await agentic(
    `Returns whether wordA rhymes with wordB`,
    { wordA, wordB }
  );
}

See the full API in the references: Python | TypeScript.

Use your tools and types

Expose the full programmatic power of an SDK or API. No MCP server is required. Simply pass it into your agentic functions scope. You can also expose existing remote or local MCP tools by passing an MCP configuration path. See here for more information.

Prerequisites:

Python: run pip install art or uv add art
TypeScript: run npm install figlet (or use pnpm, bun)

from agentica.logging import set_default_agent_listener
set_default_agent_listener(None)

from agentica import agentic
from art import text2art

@agentic(text2art)
async def greet(name: str) -> str:
    """
    Use the provided function to create a fancy greeting.
    """
    ...

print(await greet("agentica"))

import { agentic } from '@symbolica/agentica';
import figlet from 'figlet';

async function greet(name: string): Promise<string> {
  return await agentic(
    `Use the provided function to create a fancy greeting`,
    { figletText: figlet.text, name },
  );
}

console.log(await greet("agentica"));

    __  __     ____           ___                    __  _
   / / / /__  / / /___       /   | ____ ____  ____  / /_(_)________ _
  / /_/ / _ \/ / / __ \     / /| |/ __ `/ _ \/ __ \/ __/ / ___/ __ `/
 / __  /  __/ / / /_/ /    / ___ / /_/ /  __/ / / / /_/ / /__/ /_/ /
/_/ /_/\___/_/_/\____( )  /_/  |_\__, /\___/_/ /_/\__/_/\___/\__,_/
                     |/         /____/

Objects passed to scope or as arguments are presented without private methods or field names (fields with a leading _).
Async functions in scope are exposed to the REPL as synchronous functions returning Future[T]. The REPL includes a top-level event loop, so agents can await these futures directly and use standard patterns like asyncio.gather().

Streaming

Stream responses as they are being generated.

import asyncio
from agentica import agentic
from agentica.logging.loggers import StreamLogger


@agentic(model='openai/gpt-5.2')
async def word_counter(corpus: str) -> int:
    """Returns the number of words in the corpus."""
    ...

stream = StreamLogger()
with stream:
    res = asyncio.create_task(
      word_counter("True! -- nervous -- very, very dreadfully nervous I had been and am; but why will you say that I am mad? The disease had sharpened my senses -- not destroyed -- not dulled them. Above all was the sense of hearing acute. I heard all things in the heaven and in the earth. I heard many things in hell. How, then, am I mad? Hearken! and observe how healthily -- how calmly I can tell you the whole story.")
    )

async for chunk in stream:
    if chunk.role == 'agent':
        print(chunk, end="", flush=True)
print()

print(await res)

import { agentic } from '@symbolica/agentica';

async function summarize(text: string): Promise<string> {
  const result = await agentic<string>(
    `Summarize the following text in two sentences.`,
    { text },
    { listener: (iid, chunk) => process.stdout.write(chunk.content) }
  );

  return result;
}

const summary = await summarize(
  'True! -- nervous -- very, very dreadfully nervous I had been and am; but why will you say that I am mad? The disease had sharpened my senses -- not destroyed -- not dulled them. Above all was the sense of hearing acute. I heard all things in the heaven and in the earth. I heard many things in hell. How, then, am I mad? Hearken! and observe how healthily -- how calmly I can tell you the whole story.'
);
console.log('\nFinal summary:', summary);

Using MCP

from dataclasses import dataclass

from agentica import agentic

@dataclass
class Report:
    name: str
    blurb: str

@agentic(mcp="./my-mcp.json")
async def run_report(company: str) -> Report:
    """
    Create a brief company report for the given company name.

    Returns a report with:
    - name: The official company name
    - blurb: A 1-2 sentence description of the company's main business focus
    """
    ...

// MCP support via unMCP coming soon for TypeScript

Advanced

You can expose custom exceptions in scope so they can be raised from within execution (see here, including information on logging, retries, rate-limiting and prefix caching). For more examples, see Examples.

Getting Started

Core Concepts

Guides

Integrations

Using agentic

When to use agentic functions

The basics

Use your tools and types

Streaming

Using MCP

Advanced

​Using agentic

​When to use agentic functions

​The basics

​Use your tools and types

​Streaming

​Using MCP

​Advanced

Using agentic

When to use agentic functions

The basics

Use your tools and types

Streaming

Using MCP

Advanced