Skip to main content
Magic functions are stateless, decorator‑based functions implemented by the model; each call is independent. The de facto way to implement a magic function is via the @magic decorator.

​
Magic decorator

This function is primarily meant to be used as a decorator on functions that you wish to be AI-implemented. Function bodies should contain a descriptive doc-string, but otherwise be empty (body contains ...). 
def magic[F: FunctionType](
    *scope: Any,
    system: str | None = None,
    premise: str | None = None,
    mcp: str | None = None,
    persist: bool = False,
    model:  Literal[
        'openai:gpt-3.5-turbo',
        'openai:gpt-4o',
        'openai:gpt-4.1',
        'openai:gpt-5',
        'anthropic:claude-sonnet-4',
        'anthropic:claude-opus-4.1',
        'anthropic:claude-sonnet-4.5',
    ] = 'openai:gpt-4.1',
    max_tokens: int = 2048,
    listener: Callable[[], AgentListener] | DefaultAgentListener | None = DEFAULT_AGENT_LISTENER,
) -> Callable[[F], F]:
    ...
Parameters
​
*scope
list[Any]
A list of runtime resources that are in scope and which may be used during the execution of the magic function. Resources in scope may be arbitrary Python functions, methods, objects, iterators, types or any other Python value.
​
system
str | None
An optional system prompt for the magic function. This will be the system prompt of all invocations of this magic function.
This argument cannot be provided along with the premise argument.
​
premise
str | None
An optional premise for the magic function. This will be attached to the system prompt of all invocations of this magic function.
This argument cannot be provided along with the system argument.
​
mcp
str | None
The string of a path to a .json file representing an MCP configuration. Any servers and/or tools of servers outlined in the config can be used during the execution of the magic function.
​
persist
bool
Whether to persist the function state/history between calls. Defaults to False.
​
model
str
The model used to execute the magic function.One of:
  • openai:gpt-3.5-turbo
  • openai:gpt-4o
  • openai:gpt-4.1
  • openai:gpt-5
  • anthropic:claude-sonnet-4
  • anthropic:claude-opus-4.1
  • anthropic:claude-sonnet-4.5
Defaults to openai:gpt-4.1.
​
max_tokens
int
The maximum number of tokens that the agent can generate during one round of inference.Defaults to 2048.
​
listener
Callable[[], AgentListener] | DefaultAgentListener | None
Optional listener constructor for logging the magic function’s activity and chat history.
The default agent listener is the StandardListener, but can be changed for all agents and magic functions in the current scope with set_default_agent_listener. If a context-specific logger is used in the current scope, the logger will be added to the listener: if the listener is None, then the listener will be set to:
  • the default agent listener, if it is not None, or
  • the StandardListener, if the default agent listener is None