Skip to main content
This is detailed usage documentation. New to Agentica? 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 a 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

Agentica’s agentic 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`.
    """
    ...
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"))

    __  __     ____           ___                    __  _
   / / / /__  / / /___       /   | ____ ____  ____  / /_(_)________ _
  / /_/ / _ \/ / / __ \     / /| |/ __ `/ _ \/ __ \/ __/ / ___/ __ `/
 / __  /  __/ / / /_/ /    / ___ / /_/ /  __/ / / / /_/ / /__/ /_/ /
/_/ /_/\___/_/_/\____( )  /_/  |_\__, /\___/_/ /_/\__/_/\___/\__,_/
                     |/         /____/
  • 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. 
from agentica import agentic
from agentica.logging.loggers.stream_logger import StreamLogger


@agentic(model='openai:gpt-4o')
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)

​
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
    """
    ...

​
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.