Models 

Clock

A wrapper for a deferred-loading field. When the value is read from this

created_at

Created at

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

get_state_display(*, field=<django.db.models.CharField: state>): Shows the label of the state. See get_FOO_display() for more information.

objects = <django.db.models.Manager object>

class agency.models.Provider(*args, **kwargs)[source]

Bases: Model

Database table: agency_provider

🔌 Represents a provider configuration for inference services.

Examples: Ollama, OpenAI, FAL, OpenAI-compatible gateways.

Credentials stay in the environment; api_key_env is only the variable name.

Parameters:

id (UUIDField) – Primary key: Id
name (CharField) – Nombre
url (CharField) – Url
kind (CharField) – Kind
api_key_env (CharField) – Api key env

Reverse relationships:

Parameters:: models (Reverse ForeignKey from Model) – All models of this provider (related name of provider)

class Kind(value)[source]

Bases: TextChoices

OLLAMA = 'ollama'

OPENAI = 'openai'

FAL = 'fal'

OPENAI_COMPATIBLE = 'openai_compatible'

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Nombre

A wrapper for a deferred-loading field. When the value is read from this

url

Type: CharField

Url

A wrapper for a deferred-loading field. When the value is read from this

kind

Type: CharField

Kind

Choices:

ollama
openai
fal
openai_compatible

A wrapper for a deferred-loading field. When the value is read from this

api_key_env

Type: CharField

Api key env

A wrapper for a deferred-loading field. When the value is read from this

models: QuerySet

Type: Reverse ForeignKey from Model

All models of this provider (related name of provider)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

save(*args, **kwargs)[source]

update_models()[source]: Schedule a Celery task to check the provider and reload the models.

sync_models()[source]

Fetch models from the provider API and upsert local Model rows.

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_kind_display(*, field=<django.db.models.CharField: kind>): Shows the label of the kind. See get_FOO_display() for more information.

objects = <django.db.models.Manager object>

class agency.models.Model(*args, **kwargs)[source]

Bases: Model

Database table: agency_model

🧠 A LLM model that can be used to generate messages.

Parameters:

id (UUIDField) – Primary key: Id
name (CharField) – Nombre
notes (TextField) – Notas
tools (BooleanField) – Heramientas
vision (BooleanField) – Visión
metadata (JSONField) – Metadatos
modified_at (DateTimeField) – Modificado el
size (FloatField) – Tamaño
parameter_size (CharField) – Parametros
digest (CharField) – Comprobación
format (CharField) – Formato
family (CharField) – Familia
removed (BooleanField) – Removed

Relationship fields:

Parameters:: provider (ForeignKey to Provider) – Proveedor (related name: models)

Reverse relationships:

Parameters:: agents (Reverse ForeignKey from Agent) – All agents of this modelo (related name of model)

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Nombre

A wrapper for a deferred-loading field. When the value is read from this

provider

Type: ForeignKey to Provider

Proveedor (related name: models)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

notes

Type: TextField

Notas

A wrapper for a deferred-loading field. When the value is read from this

tools

Heramientas

A wrapper for a deferred-loading field. When the value is read from this

vision

Visión

A wrapper for a deferred-loading field. When the value is read from this

metadata

Type: JSONField

Metadatos

A wrapper for a deferred-loading field. When the value is read from this

modified_at

Modificado el

A wrapper for a deferred-loading field. When the value is read from this

size

Type: FloatField

Tamaño

A wrapper for a deferred-loading field. When the value is read from this

parameter_size

Type: CharField

Parametros

A wrapper for a deferred-loading field. When the value is read from this

digest

Type: CharField

Comprobación

A wrapper for a deferred-loading field. When the value is read from this

format

Type: CharField

Formato

A wrapper for a deferred-loading field. When the value is read from this

family

Type: CharField

Familia

A wrapper for a deferred-loading field. When the value is read from this

removed

Removed

A wrapper for a deferred-loading field. When the value is read from this

agents: QuerySet

Type: Reverse ForeignKey from Agent

All agents of this modelo (related name of model)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_next_by_modified_at(*, field=<django.db.models.DateTimeField: modified_at>, is_next=True, **kwargs): Finds next instance based on modified_at. See get_next_by_FOO() for more information.

get_previous_by_modified_at(*, field=<django.db.models.DateTimeField: modified_at>, is_next=False, **kwargs): Finds previous instance based on modified_at. See get_previous_by_FOO() for more information.

objects = <django.db.models.Manager object>

provider_id: Internal field, use provider instead.

class agency.models.Tool(*args, **kwargs)[source]

Bases: Model

Database table: agency_tool

🛠 Python tools catalog.

Parameters:

id (CharField) – Primary key: Id
namespace (CharField) – Namespace
definition (CharField) –
Definition

The module.path.function_name of the tool to be lazy imported.
help (TextField) – Help
icon (ImageField) – Icon

Reverse relationships:

Parameters:: agents (Reverse ManyToManyField from Agent) – All agents of this tool (related name of tools)

id

Type: CharField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

namespace

Type: CharField

Namespace

A wrapper for a deferred-loading field. When the value is read from this

definition

Type: CharField

Definition

help

Type: TextField

Help

A wrapper for a deferred-loading field. When the value is read from this

icon

Type: ImageField

Icon

Just like the FileDescriptor, but for ImageFields. The only difference is

agents: QuerySet

Type: Reverse ManyToManyField from Agent

All agents of this tool (related name of tools)

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

objects = <django.db.models.Manager object>

class agency.models.Skill(*args, **kwargs)[source]

Bases: Model

Database table: agency_skill

🎯 Skill represents a capability or skill.

Parameters:

id (UUIDField) – Primary key: Id
name (CharField) – Nombre
description (TextField) – Descripción
text (TextField) – Text

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Nombre

A wrapper for a deferred-loading field. When the value is read from this

description

Type: TextField

Descripción

A wrapper for a deferred-loading field. When the value is read from this

text

Type: TextField

Text

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

objects = <django.db.models.Manager object>

class agency.models.Voice(*args, **kwargs)[source]

Bases: Model

Database table: agency_voice

🔊 TTS voice (provider + engine-specific key).

Parameters:

id (UUIDField) – Primary key: Id
name (CharField) – Nombre
provider (CharField) – TTS provider
key (CharField) – Voice key
language (CharField) – Idioma
locale (CharField) – Traducción
gender (CharField) – Gender
quality (CharField) – Quality

Reverse relationships:

Parameters:: agents (Reverse ForeignKey from Agent) – All agents of this voice (related name of voice)

class Provider(value)[source]

Bases: TextChoices

PIPER = 'piper'

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Nombre

A wrapper for a deferred-loading field. When the value is read from this

provider

Type: CharField

TTS provider

Choices:

piper

A wrapper for a deferred-loading field. When the value is read from this

key

Type: CharField

Voice key

A wrapper for a deferred-loading field. When the value is read from this

language

Type: CharField

Idioma

A wrapper for a deferred-loading field. When the value is read from this

locale

Type: CharField

Traducción

A wrapper for a deferred-loading field. When the value is read from this

gender

Type: CharField

Gender

A wrapper for a deferred-loading field. When the value is read from this

quality

Type: CharField

Quality

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

agents

Type: Reverse ForeignKey from Agent

All agents of this voice (related name of voice)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

get_provider_display(*, field=<django.db.models.CharField: provider>): Shows the label of the provider. See get_FOO_display() for more information.

objects = <django.db.models.Manager object>

class agency.models.Agent(*args, **kwargs)[source]

Bases: Model

Database table: agency_agent

😐 Agents are the logical entities that perform missions.

An agent defines how missions are executed by specifying: - the underlying language model - the set of tools it can use - the system prompt to use - the TTS voice used when the agent speaks

Parameters:

id (UUIDField) – Primary key: Id
name (CharField) – Name
namespace (CharField) – Namespace
system_key (CharField) – System key
shipped_content_hash (CharField) – Shipped content hash
is_customized (BooleanField) – Customized
deep (BooleanField) – Deep
instructions (TextField) – Instrucciones
icon (ImageField) – Icon
created_at (DateTimeField) – Created at
updated_at (DateTimeField) – Updated at

Relationship fields:

Parameters:

model (ForeignKey to Model) – Model (related name: agents)
voice (ForeignKey to Voice) – Voice (related name: agents)
tools (ManyToManyField to Tool) – Tools (related name: agents)

Reverse relationships:

Parameters:

executions (Reverse ForeignKey from Execution) – All executions of this agent (related name of agent)
threads (Reverse ForeignKey from Thread) – All threads of this agent (related name of agent)
interruptions (Reverse ForeignKey from Interruption) – All interruptions of this agent (related name of agent)
messages (Reverse ForeignKey from Message) – All messages of this agent (related name of agent)

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Name

A wrapper for a deferred-loading field. When the value is read from this

namespace

Type: CharField

Namespace

A wrapper for a deferred-loading field. When the value is read from this

system_key

Type: CharField

System key

A wrapper for a deferred-loading field. When the value is read from this

shipped_content_hash

Type: CharField

Shipped content hash

A wrapper for a deferred-loading field. When the value is read from this

is_customized

Customized

A wrapper for a deferred-loading field. When the value is read from this

model

Type: ForeignKey to Model

Model (related name: agents)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

voice

Type: ForeignKey to Voice

Voice (related name: agents)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

tools

Type: ManyToManyField to Tool

Tools (related name: agents)

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager

deep

Deep

A wrapper for a deferred-loading field. When the value is read from this

instructions

Type: TextField

Instrucciones

A wrapper for a deferred-loading field. When the value is read from this

icon

Type: ImageField

Icon

Just like the FileDescriptor, but for ImageFields. The only difference is

created_at

Created at

A wrapper for a deferred-loading field. When the value is read from this

updated_at

Updated at

A wrapper for a deferred-loading field. When the value is read from this

executions: QuerySet

Type: Reverse ForeignKey from Execution

All executions of this agent (related name of agent)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

threads: QuerySet

Type: Reverse ForeignKey from Thread

All threads of this agent (related name of agent)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

interruptions: QuerySet

Type: Reverse ForeignKey from Interruption

All interruptions of this agent (related name of agent)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

static by_name(name)[source]

Get an agent by its name.

Parameters:: name (str) – Agent name to search for
Returns:: Agent instance
Raises:: ValueError – If agent not found
Return type:: Agent

get_tools()[source]

Get the list of tool functions from Agent.tools.

Each tool has a definition like “agency.tools.tavily.internet_search” that is lazy imported and returned as a list of callable functions.

Supports both: - Functions decorated with @tool() (e.g., “agency.tools.basic.calculate”) - BaseTool classes that need to be instantiated (e.g., “agency.tools.interpreter.PythonREPLTool”)

Returns:: List of tool functions/instances
Return type:: list

test(user_message)[source]

Invoke the agent with a user message and tools.

Parameters:: user_message (str) – Message to send to the agent
Returns:: Agent output dictionary
Return type:: dict

execute(mission, user, execution=None)[source]

Execute a mission commanded by a user.

Parameters:

mission (Mission | str) – Mission instance or mission name
user (AbstractUser) – User executing the mission
execution (Execution | None) – Optional pre-created Execution (and Thread). When set, reuse it instead of creating a new pair (API dispatch path).

Returns:

Execution result dictionary

Return type:

dict

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_next_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=True, **kwargs): Finds next instance based on updated_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

get_previous_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=False, **kwargs): Finds previous instance based on updated_at. See get_previous_by_FOO() for more information.

messages

Type: Reverse ForeignKey from Message

All messages of this agent (related name of agent)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

model_id: Internal field, use model instead.

objects = <django.db.models.Manager object>

voice_id: Internal field, use voice instead.

class agency.models.Mission(*args, **kwargs)[source]

Bases: Model

Database table: agency_mission

🎯 A Mission defines a reusable objective that an agent can perform.

A mission describes what should be done, independent of who executes it or how many times it is run. It typically encapsulates a prompt, goal, or task definition that can be executed by different agents.

When a mission is executed: - an Execution is created to represent the user request - a Thread is created to hold execution state - one or more Runs advance the mission through the thread

Parameters:

id (UUIDField) – Primary key: Id
name (CharField) – Name
namespace (CharField) – Namespace
system_key (CharField) – System key
shipped_content_hash (CharField) – Shipped content hash
is_customized (BooleanField) – Customized
prompt (TextField) – Prompt
loop_prompt (TextField) – Loop prompt
max_iterations (PositiveSmallIntegerField) – Max iterations
loop_delay_seconds (PositiveIntegerField) – Loop delay seconds
created_at (DateTimeField) – Created at
updated_at (DateTimeField) – Updated at

Reverse relationships:

Parameters:: executions (Reverse ForeignKey from Execution) – All executions of this mission (related name of mission)

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Name

A wrapper for a deferred-loading field. When the value is read from this

namespace

Type: CharField

Namespace

A wrapper for a deferred-loading field. When the value is read from this

system_key

Type: CharField

System key

A wrapper for a deferred-loading field. When the value is read from this

shipped_content_hash

Type: CharField

Shipped content hash

A wrapper for a deferred-loading field. When the value is read from this

is_customized

Customized

A wrapper for a deferred-loading field. When the value is read from this

prompt

Type: TextField

Prompt

A wrapper for a deferred-loading field. When the value is read from this

loop_prompt

Type: TextField

Loop prompt

A wrapper for a deferred-loading field. When the value is read from this

max_iterations

Type: PositiveSmallIntegerField

Max iterations

A wrapper for a deferred-loading field. When the value is read from this

loop_delay_seconds

Loop delay seconds

A wrapper for a deferred-loading field. When the value is read from this

created_at

Created at

A wrapper for a deferred-loading field. When the value is read from this

updated_at

Updated at

A wrapper for a deferred-loading field. When the value is read from this

executions: QuerySet

Type: Reverse ForeignKey from Execution

All executions of this mission (related name of mission)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

property is_loop: bool

clean()[source]

save(*args, **kwargs)[source]

static by_name(name)[source]

Get a mission by its name.

Parameters:: name (str) – Mission name to search for
Returns:: Mission instance
Raises:: ValueError – If mission not found
Return type:: Mission

dispatch(agent=None, user=None, execution=None)[source]

Create a Celery task to execute the mission.

Parameters:

agent (Agent) – Agent to execute the mission (uses first available if not provided)
user (AbstractUser) – User executing the mission
execution (Execution | None) – Optional pre-created Execution to reuse (API dispatch)

Returns:

Celery AsyncResult for the task

Return type:

AsyncResult

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_next_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=True, **kwargs): Finds next instance based on updated_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

get_previous_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=False, **kwargs): Finds previous instance based on updated_at. See get_previous_by_FOO() for more information.

objects = <django.db.models.Manager object>

class agency.models.Execution(*args, **kwargs)[source]

Bases: Model

Database table: agency_execution

⚡ Execution represents a single business-level request to run a Mission with a specific Agent on behalf of a user.

An Execution coordinates the work required to fulfill that request and may involve one or more Threads. Each Thread represents an independent conversational timeline, while the Execution groups them under a single intent and lifecycle.

An Execution is responsible for: - tracking the overall status of the mission - grouping related Threads - enabling aggregation of results once all threads complete

Executions are independent and repeatable: the same Mission can be run multiple times, producing separate Executions with their own Threads, Runs, and Checkpoints.

Parameters:

id (UUIDField) – Primary key: Id
status (CharField) – Status
result (JSONField) – Result
metadata (JSONField) – Metadata
iteration (PositiveIntegerField) – Iteration
max_iterations (PositiveSmallIntegerField) – Max iterations
loop_status (CharField) – Loop status
next_run_at (DateTimeField) – Next run at
loop_decision (JSONField) – Loop decision
created_at (DateTimeField) – Created at
updated_at (DateTimeField) – Updated at

Relationship fields:

Parameters:

user (ForeignKey to User) – User (related name: executions)
agent (ForeignKey to Agent) – Agent (related name: executions)
mission (ForeignKey to Mission) – Mission (related name: executions)

Reverse relationships:

Parameters:: threads (Reverse ForeignKey from Thread) – All threads of this execution (related name of execution)

class Status(value)[source]

Bases: TextChoices

STARTING = 'starting'

RUNNING = 'running'

SUCCESS = 'success'

INTERRUPTED = 'interrupted'

CANCELLED = 'cancelled'

TIMEOUT = 'timeout'

ERROR = 'error'

WAITING = 'waiting'

BLOCKED = 'blocked'

LIMIT_REACHED = 'limit_reached'

class LoopStatus(value)[source]

Bases: TextChoices

IDLE = 'idle'

RUNNING = 'running'

EVALUATING = 'evaluating'

WAITING = 'waiting'

BLOCKED = 'blocked'

COMPLETED = 'completed'

FAILED = 'failed'

LIMIT_REACHED = 'limit_reached'

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

user

Type: ForeignKey to User

User (related name: executions)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

agent

Type: ForeignKey to Agent

Agent (related name: executions)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

mission

Type: ForeignKey to Mission

Mission (related name: executions)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

status

Type: CharField

Status

Choices:

starting
running
success
interrupted
cancelled
timeout
error
waiting
blocked
limit_reached

A wrapper for a deferred-loading field. When the value is read from this

result

Type: JSONField

Result

A wrapper for a deferred-loading field. When the value is read from this

metadata

Type: JSONField

Metadata

A wrapper for a deferred-loading field. When the value is read from this

iteration

Iteration

A wrapper for a deferred-loading field. When the value is read from this

max_iterations

Type: PositiveSmallIntegerField

Max iterations

A wrapper for a deferred-loading field. When the value is read from this

loop_status

Type: CharField

Loop status

Choices:

idle
running
evaluating
waiting
blocked
completed
failed
limit_reached

A wrapper for a deferred-loading field. When the value is read from this

next_run_at

Next run at

A wrapper for a deferred-loading field. When the value is read from this

loop_decision

Type: JSONField

Loop decision

A wrapper for a deferred-loading field. When the value is read from this

created_at

Created at

A wrapper for a deferred-loading field. When the value is read from this

updated_at

Updated at

A wrapper for a deferred-loading field. When the value is read from this

threads: QuerySet

Type: Reverse ForeignKey from Thread

All threads of this execution (related name of execution)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

agent_id: Internal field, use agent instead.

get_loop_status_display(*, field=<django.db.models.CharField: loop_status>): Shows the label of the loop_status. See get_FOO_display() for more information.

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_next_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=True, **kwargs): Finds next instance based on updated_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

get_previous_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=False, **kwargs): Finds previous instance based on updated_at. See get_previous_by_FOO() for more information.

get_status_display(*, field=<django.db.models.CharField: status>): Shows the label of the status. See get_FOO_display() for more information.

mission_id: Internal field, use mission instead.

objects = <django.db.models.Manager object>

user_id: Internal field, use user instead.

class agency.models.Thread(*args, **kwargs)[source]

Bases: Model

Database table: agency_thread

🧭 Thread represents a single conversational timeline with a human user.

A Thread is the long-lived identity used by LangGraph to scope memory: all Runs, Checkpoints, and Interruptions are written and retrieved under the same thread_id (this model’s UUID).

A thread may exist in two modes:

Orchestrated conversation (execution is set) - The thread is part of a larger Execution (mission + agent + user). - The Execution groups one or more threads under a single business

request, while each Thread remains an independent conversational timeline.
Personal conversation (no execution associated) - Durable operator chat with an Agent (execution_id is NULL). - At most one active personal Thread per (user, agent).

Threads are linear timelines: each invoke() or resume() advances the state forward and typically produces new checkpoints. To continue a conversation, call LangGraph again using the same thread_id; to start a new conversation, create a new Thread.

Parameters:

id (UUIDField) – Primary key: Id
created_at (DateTimeField) – Created at
title (CharField) – Title
is_active (BooleanField) – Is active

Relationship fields:

Parameters:

user (ForeignKey to User) – User (related name: threads)
agent (ForeignKey to Agent) – Agent (related name: threads)
execution (ForeignKey to Execution) – Execution (related name: threads)

Reverse relationships:

Parameters:

runs (Reverse ForeignKey from Run) – All runs of this thread (related name of thread)
checkpoints (Reverse ForeignKey from Checkpoint) – All checkpoints of this thread (related name of thread)

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

user

Type: ForeignKey to User

User (related name: threads)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

agent

Type: ForeignKey to Agent

Agent (related name: threads)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

execution

Type: ForeignKey to Execution

Execution (related name: threads)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

created_at

Created at

A wrapper for a deferred-loading field. When the value is read from this

title

Type: CharField

Title

A wrapper for a deferred-loading field. When the value is read from this

is_active

Is active

A wrapper for a deferred-loading field. When the value is read from this

runs: QuerySet

Type: Reverse ForeignKey from Run

All runs of this thread (related name of thread)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

checkpoints: QuerySet

Type: Reverse ForeignKey from Checkpoint

All checkpoints of this thread (related name of thread)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

get_execution()[source]

Get the execution of the thread.

Returns:: Execution instance
Return type:: Execution

create_run(status=None)[source]

Start a new run.

Parameters:: status (Status) – Optional initial status for the run
Returns:: New Run instance
Return type:: Run

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

agent_id: Internal field, use agent instead.

execution_id: Internal field, use execution instead.

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

objects = <django.db.models.Manager object>

user_id: Internal field, use user instead.

class agency.models.Run(*args, **kwargs)[source]

Bases: Model

Database table: agency_run

A Run represents a single technical execution attempt of a thread.

A run tracks one concrete invocation of a LangGraph execution. While a thread represents a continuous execution timeline, runs capture the individual attempts to advance that timeline.

Runs may: - complete successfully - fail due to errors - pause due to interruptions (human-in-the-loop) - resume execution in subsequent runs

Multiple runs can belong to the same thread and execution, allowing retries and resumptions to be represented explicitly.

Run status reflects the outcome of a specific execution attempt, not the overall mission result.

Parameters:

id (BigAutoField) – Primary key: Id
config (JSONField) – Config
status (CharField) – Status
error (JSONField) – Error
metadata (JSONField) – Metadata
total_tokens (PositiveIntegerField) – Total tokens
created_at (DateTimeField) – Created at
updated_at (DateTimeField) – Updated at

Relationship fields:

Parameters:: thread (ForeignKey to Thread) – Thread (related name: runs)

Reverse relationships:

Parameters:: checkpoints (Reverse ForeignKey from Checkpoint) – All checkpoints of this run (related name of run)

class Status(value)[source]

Bases: TextChoices

PENDING = 'pending'

RESUMING = 'resuming'

STARTING = 'starting'

RUNNING = 'running'

SUCCESS = 'success'

INTERRUPTED = 'interrupted'

CANCELLED = 'cancelled'

TIMEOUT = 'timeout'

ERROR = 'error'

id

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

config

Type: JSONField

Config

A wrapper for a deferred-loading field. When the value is read from this

thread

Type: ForeignKey to Thread

Thread (related name: runs)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

status

Type: CharField

Status

Choices:

pending
resuming
starting
running
success
interrupted
cancelled
timeout
error

A wrapper for a deferred-loading field. When the value is read from this

error

Type: JSONField

Error

A wrapper for a deferred-loading field. When the value is read from this

metadata

Type: JSONField

Metadata

A wrapper for a deferred-loading field. When the value is read from this

total_tokens

Total tokens

A wrapper for a deferred-loading field. When the value is read from this

created_at

Created at

A wrapper for a deferred-loading field. When the value is read from this

updated_at

Updated at

A wrapper for a deferred-loading field. When the value is read from this

checkpoints: QuerySet

Type: Reverse ForeignKey from Checkpoint

All checkpoints of this run (related name of run)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

get_thread()[source]

Get the thread of the run.

Returns:: Thread instance
Return type:: Thread

save_status(status=Run.Status.STARTING)[source]

Save the run status.

Parameters:: status (Status) – Status to set (defaults to STARTING)

last_checkpoint()[source]

Get the last checkpoint of the run.

Returns:: Last Checkpoint instance or None
Return type:: ‘Checkpoint’ | None

has_interruption()[source]

Check if the run has an interruption.

Returns:: True if run has an interruption, False otherwise
Return type:: bool

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_next_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=True, **kwargs): Finds next instance based on updated_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

get_previous_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=False, **kwargs): Finds previous instance based on updated_at. See get_previous_by_FOO() for more information.

get_status_display(*, field=<django.db.models.CharField: status>): Shows the label of the status. See get_FOO_display() for more information.

objects = <django.db.models.Manager object>

thread_id: Internal field, use thread instead.

class agency.models.Checkpoint(*args, **kwargs)[source]

Bases: Model

Database table: agency_checkpoint

A Checkpoint is a durable snapshot of a LangGraph execution state.

A checkpoint captures the full logical state of the graph at a specific point in time, scoped to a thread. It allows execution to be resumed, retried, or inspected after the fact.

A checkpoint includes: - the serialized graph state (channels and values) - metadata produced by the runtime - a reference to the parent checkpoint - associated pending writes (CheckpointWrite entries)

Checkpoints are immutable once written. Execution always resumes from the latest checkpoint in a thread unless an explicit fork or rollback mechanism is implemented.

Checkpoints enable long-running, fault-tolerant, and human-in-the-loop workflows by separating state persistence from execution.

Parameters:

id (BigAutoField) – Primary key: Id
namespace (CharField) – Namespace
checkpoint_id (CharField) – Checkpoint id
ts (DateTimeField) – Ts
data (JSONField) – Data
metadata (JSONField) – Metadata
new_versions (JSONField) – New versions
type (CharField) – Type
blob (BinaryField) –
Blob

Contains the fully serialized graph state using serde.
created_at (DateTimeField) – Created at

Relationship fields:

Parameters:

thread (ForeignKey to Thread) – Thread (related name: checkpoints)
run (ForeignKey to Run) – Run (related name: checkpoints)
parent (ForeignKey to Checkpoint) – Parent (related name: children)

Reverse relationships:

Parameters:

children (Reverse ForeignKey from Checkpoint) – All children of this checkpoint (related name of parent)
interruptions (Reverse ForeignKey from Interruption) – All interruptions of this checkpoint (related name of checkpoint)
messages (Reverse ForeignKey from Message) – All messages of this checkpoint (related name of checkpoint)

id

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

thread

Type: ForeignKey to Thread

Thread (related name: checkpoints)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

run

Type: ForeignKey to Run

Run (related name: checkpoints)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

namespace

Type: CharField

Namespace

A wrapper for a deferred-loading field. When the value is read from this

checkpoint_id

Type: CharField

Checkpoint id

A wrapper for a deferred-loading field. When the value is read from this

parent

Type: ForeignKey to Checkpoint

Parent (related name: children)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

ts

Ts

A wrapper for a deferred-loading field. When the value is read from this

data

Type: JSONField

Data

A wrapper for a deferred-loading field. When the value is read from this

metadata

Type: JSONField

Metadata

A wrapper for a deferred-loading field. When the value is read from this

new_versions

Type: JSONField

New versions

A wrapper for a deferred-loading field. When the value is read from this

type

Type: CharField

Type

A wrapper for a deferred-loading field. When the value is read from this

blob

Type: BinaryField

Blob

created_at

Created at

A wrapper for a deferred-loading field. When the value is read from this

interruptions: QuerySet

Type: Reverse ForeignKey from Interruption

All interruptions of this checkpoint (related name of checkpoint)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

messages: QuerySet

Type: Reverse ForeignKey from Message

All messages of this checkpoint (related name of checkpoint)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

children: QuerySet

Type: Reverse ForeignKey from Checkpoint

All children of this checkpoint (related name of parent)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

deserialize_blob()[source]

Deserialize the blob using the same serde as LangGraph.

Returns:: The deserialized checkpoint state dictionary

get_last_tool_call_message()[source]

Get the last Message in this checkpoint that has tool_calls.

This is typically an AIMessage where the agent decided to call tools. The tool_calls field contains the list of tools that were requested.

Returns:: The last Message with tool_calls, or None if no such message exists
Return type:: Message | None

get_interruptions()[source]

Get all interruptions for this checkpoint.

Returns:: QuerySet of Interruption instances ordered by creation time
Return type:: QuerySet

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

objects = <django.db.models.Manager object>

parent_id: Internal field, use parent instead.

run_id: Internal field, use run instead.

thread_id: Internal field, use thread instead.

class agency.models.CheckpointWrite(*args, **kwargs)[source]

Bases: Model

Database table: agency_checkpointwrite

A CheckpointWrite represents a pending side effect emitted during LangGraph execution.

When a node produces an effect (a tool result or an interruption), it is recorded as a write to a channel and applied later by the runtime when execution is resumed via pending_writes.

CheckpointWrite persists those pending writes so execution can be safely paused, resumed, or retried.

Parameters:

id (BigAutoField) – Primary key: Id
thread_id (CharField) – Thread id
checkpoint_id (CharField) – Checkpoint id
checkpoint_ns (CharField) – Checkpoint ns
task_id (CharField) – Task id
task_path (CharField) – Task path
channel (CharField) –
Channel

The special ‘__interrupt__’ channel indicates that the graph execution intentionally paused and is awaiting external input (e.g. human-in-the-loop). An interrupt write is consumed when execution is resumed.
value_type (CharField) – Value type
value_blob (BinaryField) – Value blob
created_at (DateTimeField) – Created at

id

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

thread_id

Type: CharField

Thread id

A wrapper for a deferred-loading field. When the value is read from this

checkpoint_id

Type: CharField

Checkpoint id

A wrapper for a deferred-loading field. When the value is read from this

checkpoint_ns

Type: CharField

Checkpoint ns

A wrapper for a deferred-loading field. When the value is read from this

task_id

Type: CharField

Task id

A wrapper for a deferred-loading field. When the value is read from this

task_path

Type: CharField

Task path

A wrapper for a deferred-loading field. When the value is read from this

channel

Type: CharField

Channel

The special ‘__interrupt__’ channel indicates that the graph execution intentionally paused and is awaiting external input (e.g. human-in-the-loop).

value_type

Type: CharField

Value type

A wrapper for a deferred-loading field. When the value is read from this

value_blob

Type: BinaryField

Value blob

A wrapper for a deferred-loading field. When the value is read from this

created_at

Created at

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

objects = <django.db.models.Manager object>

class agency.models.Interruption(*args, **kwargs)[source]

Bases: Model

Database table: agency_interruption

😀 Represents an explicit interruption raised by an Agent during execution, typically to request external input (e.g. human-in-the-loop).

An Interruption pauses the execution of a Thread at a specific Checkpoint. Resuming an interruption advances the thread forward.

The interruption is always triggered by an Agent. The Agent and the originating user (i.e. the user who dispatched the mission or owns the thread context) can be derived from the associated Thread and Execution.

The user assigned to handle the interruption may be different from the originating user. This allows questions to be routed to other users (e.g. operators, reviewers, or managers).

Optionally, an interruption may also be resolved by another Agent, enabling agent-to-agent handoffs or automated resolution strategies.

Parameters:

id (UUIDField) – Primary key: Id
status (CharField) – Status
priority (IntegerField) – Priority
question (JSONField) – Question
answer (JSONField) – Answer
data (JSONField) – Data
created_at (DateTimeField) – Created at
updated_at (DateTimeField) – Updated at
answered_at (DateTimeField) – Answered at
resumed_at (DateTimeField) – Resumed at

Relationship fields:

Parameters:

checkpoint (ForeignKey to Checkpoint) –
Checkpoint (related name: interruptions)

The checkpoint where this message was created. Used to track which messages existed at the time of an interruption, enabling efficient querying when resuming.
user (ForeignKey to User) – User (related name: interruptions)
agent (ForeignKey to Agent) – Agent (related name: interruptions)

class Status(value)[source]

Bases: TextChoices

PENDING = 'pending'

ANSWERED = 'answered'

CANCELLED = 'cancelled'

TIMEOUT = 'timeout'

ERROR = 'error'

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

status

Type: CharField

Status

Choices:

pending
answered
cancelled
timeout
error

A wrapper for a deferred-loading field. When the value is read from this

checkpoint

Type: ForeignKey to Checkpoint

Checkpoint (related name: interruptions)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

priority

Type: IntegerField

Priority

A wrapper for a deferred-loading field. When the value is read from this

user

Type: ForeignKey to User

User (related name: interruptions)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

agent

Type: ForeignKey to Agent

Agent (related name: interruptions)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

question

Type: JSONField

Question

A wrapper for a deferred-loading field. When the value is read from this

answer

Type: JSONField

Answer

A wrapper for a deferred-loading field. When the value is read from this

data

Type: JSONField

Data

A wrapper for a deferred-loading field. When the value is read from this

created_at

Created at

A wrapper for a deferred-loading field. When the value is read from this

updated_at

Updated at

A wrapper for a deferred-loading field. When the value is read from this

answered_at

Answered at

A wrapper for a deferred-loading field. When the value is read from this

resumed_at

Resumed at

A wrapper for a deferred-loading field. When the value is read from this

get_thread()[source]

Get the thread of the LangGraph execution.

Returns:: Thread instance from checkpoint.run.thread
Return type:: Thread

get_to()[source]

Get the ‘to’ representation: Username(Agent.name) from the interruption.

Returns:: String in format ‘👤 Username(Agent.name)’
Return type:: str

get_from()[source]

Get the ‘from’ representation: Agent.name(Username) from the thread.

Returns:: String in format ‘😃 Agent.name(Username)’
Return type:: str

static by_id(interruption_id)[source]

Get an interruption by its ID.

Parameters:: interruption_id (str) – UUID of the interruption
Returns:: Interruption instance
Return type:: Interruption

get_message()[source]

Get the messages for this interruption.

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

agent_id: Internal field, use agent instead.

checkpoint_id: Internal field, use checkpoint instead.

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_next_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=True, **kwargs): Finds next instance based on updated_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

get_previous_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=False, **kwargs): Finds previous instance based on updated_at. See get_previous_by_FOO() for more information.

get_status_display(*, field=<django.db.models.CharField: status>): Shows the label of the status. See get_FOO_display() for more information.

objects = <django.db.models.Manager object>

user_id: Internal field, use user instead.

class agency.models.Session(*args, **kwargs)[source]

Bases: Model

Database table: agency_session

💬 Session represents a user’s browser session for real-time communication.

Sessions map Django’s request.session cookie (sessionID) to Django Channels’ scope[“session”], enabling WebSocket connections to identify and route messages to the correct user session.

Sessions are typically created when a user connects via WebSocket and are used to group related messages and events within a single browser tab/window.

The session_key corresponds to Django’s session framework session key, allowing seamless integration between HTTP and WebSocket request handling.

Parameters:

id (BigAutoField) – Primary key: ID
data (JSONField) – Data
session_key (CharField) – Clave de sesión
created_at (DateTimeField) – Creado el
updated_at (DateTimeField) – Updated at

Relationship fields:

Parameters:: user (ForeignKey to User) – Usuario (related name: agency_sessions)

Reverse relationships:

Parameters:: rooms (Reverse ManyToManyField from Room) – All rooms of this sesión (related name of sessions)

user

Type: ForeignKey to User

Usuario (related name: agency_sessions)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

data

Type: JSONField

Data

A wrapper for a deferred-loading field. When the value is read from this

session_key

Type: CharField

Clave de sesión

A wrapper for a deferred-loading field. When the value is read from this

created_at

Creado el

A wrapper for a deferred-loading field. When the value is read from this

updated_at

Updated at

A wrapper for a deferred-loading field. When the value is read from this

rooms: QuerySet

Type: Reverse ManyToManyField from Room

All rooms of this sesión (related name of sessions)

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager

channel_group_name()[source]

Get the channel group name for the session.

Returns:: String in format ‘user-<user_id>’
Return type:: str

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_next_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=True, **kwargs): Finds next instance based on updated_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

get_previous_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=False, **kwargs): Finds previous instance based on updated_at. See get_previous_by_FOO() for more information.

id

Primary key: ID

A wrapper for a deferred-loading field. When the value is read from this

objects = <django.db.models.Manager object>

user_id: Internal field, use user instead.

class agency.models.Room(*args, **kwargs)[source]

Bases: Model

Database table: agency_room

🏠 Room represents a shared conversation space for multiple user sessions.

Rooms group multiple Sessions together, enabling multi-user conversations or collaborative chat experiences. The room ID is used as the Django Channels group name for broadcasting messages to all participants.

Use cases: - Multi-user chat rooms - Shared agent conversations - Collaborative workspaces

Messages sent to a Room are broadcast to all Sessions in that Room via Django Channels WebSocket groups.

Parameters:

id (BigAutoField) – Primary key: ID
name (CharField) – Nombre
created_at (DateTimeField) – Creado el
updated_at (DateTimeField) – Updated at

Relationship fields:

Parameters:: sessions (ManyToManyField to Session) – Sesiones (related name: rooms)

Reverse relationships:

Parameters:: messages (Reverse ForeignKey from Message) – All messages of this room (related name of room)

name

Type: CharField

Nombre

A wrapper for a deferred-loading field. When the value is read from this

created_at

Creado el

A wrapper for a deferred-loading field. When the value is read from this

updated_at

Updated at

A wrapper for a deferred-loading field. When the value is read from this

sessions

Type: ManyToManyField to Session

Sesiones (related name: rooms)

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager

messages: QuerySet

Type: Reverse ForeignKey from Message

All messages of this room (related name of room)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_next_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=True, **kwargs): Finds next instance based on updated_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

get_previous_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=False, **kwargs): Finds previous instance based on updated_at. See get_previous_by_FOO() for more information.

id

Primary key: ID

A wrapper for a deferred-loading field. When the value is read from this

objects = <django.db.models.Manager object>

class agency.models.Message(*args, **kwargs)[source]

Bases: Model

Database table: agency_message

💭 Message represents a single message in a conversation thread.

Messages are the persistent record of all communication between users and agents during a Run execution, they are BaseMessages from LangChain with extra fields.

When Messages are Created:

Source of truth: - The canonical conversation state lives inside LangGraph checkpoints. - When a checkpoint is persisted, we extract messages from the checkpoint state

and store them here for efficient querying and UI needs.

Creation: - Messages are created during checkpoint persistence (CheckpointSaver),

not during middleware/model/tool execution. This ensures durability and prevents duplication across retries/resumes.

Notes: - Message.id matches the LangChain/LangGraph message id to keep referential

stability across checkpoints.

A message is linked to the checkpoint where it first appears (or the checkpoint that persisted it)

Parameters:

id (CharField) – Primary key: Id
role (CharField) – Rol
content (TextField) – Contenido
think (TextField) – Pensar
created_at (DateTimeField) – Creado el
importance (FloatField) – Importancia
metadata (JSONField) – Metadatos
tool_calls (JSONField) – Llamadas a herramienta

Relationship fields:

Parameters:

user (ForeignKey to User) – Usuario (related name: agency_messages)
room (ForeignKey to Room) – Room (related name: messages)
agent (ForeignKey to Agent) – Agent (related name: messages)
checkpoint (ForeignKey to Checkpoint) –
Checkpoint (related name: messages)

The checkpoint where this message was created. Used to track which messages existed at the time of an interruption, enabling efficient querying when resuming.
reply_to (ForeignKey to Message) – Respuesta a (related name: replies)

Reverse relationships:

Parameters:: replies (Reverse ForeignKey from Message) – All replies of this mensaje (related name of reply_to)

MAX_CONTENT = 2048

class Role(value)[source]

Bases: TextChoices

HUMAN = 'human'

SYSTEM = 'system'

ASSISTANT = 'assistant'

TOOL = 'tool'

exception AlreadyExists[source]

Bases: Exception

Raised when attempting to create a Message that already exists.

id

Type: CharField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

role

Type: CharField

Rol

Choices:

human
system
assistant
tool

A wrapper for a deferred-loading field. When the value is read from this

user

Type: ForeignKey to User

Usuario (related name: agency_messages)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

room

Type: ForeignKey to Room

Room (related name: messages)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

agent

Type: ForeignKey to Agent

Agent (related name: messages)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

checkpoint

Type: ForeignKey to Checkpoint

Checkpoint (related name: messages)

The checkpoint where this message was created. Used to track which messages

content

Type: TextField

Contenido

A wrapper for a deferred-loading field. When the value is read from this

think

Type: TextField

Pensar

A wrapper for a deferred-loading field. When the value is read from this

created_at

Creado el

A wrapper for a deferred-loading field. When the value is read from this

importance

Type: FloatField

Importancia

A wrapper for a deferred-loading field. When the value is read from this

reply_to

Type: ForeignKey to Message

Respuesta a (related name: replies)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

metadata

Type: JSONField

Metadatos

A wrapper for a deferred-loading field. When the value is read from this

tool_calls

Type: JSONField

Llamadas a herramienta

A wrapper for a deferred-loading field. When the value is read from this

static get_type_from_role(role)[source]

Get the langchain type for a role.

static get_role_from_type(message)[source]

Get the role from a langchain message type.

static register_checkpoint_message(message, checkpoint, agent)[source]

Convert a LangGraph BaseMessage to a Message model.

Parameters:

message (BaseMessage) – BaseMessage instance
checkpoint (Checkpoint) – Checkpoint instance to associate with
agent (Agent) – Agent instance (required field)

Returns:

Message instance

Raises:

Message.AlreadyExists – If message with same id already exists

Return type:

Message | None

classmethod get_messages_until_checkpoint(thread, checkpoint)[source]

Get all messages for a thread up to and including a specific checkpoint.

This is useful when resuming from an interruption to determine which messages were already persisted before the interruption occurred.

Note: When resuming, a new Run is created, but we want messages from all previous runs in the same thread. This method queries by thread, not run.

Parameters:

thread (Thread) – The Thread to query messages for
checkpoint (Checkpoint) – The Checkpoint to query up to (messages created at or before this checkpoint’s creation time)

Returns:

QuerySet of Message objects ordered by creation time

Return type:

QuerySet

to_message()[source]

Convert to a LangChain BaseMessage.

Returns:: BaseMessage instance (SystemMessage, HumanMessage, AIMessage, or ToolMessage)
Raises:: ValueError – If role is unsupported
Return type:: BaseMessage

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

agent_id: Internal field, use agent instead.

checkpoint_id: Internal field, use checkpoint instead.

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

get_role_display(*, field=<django.db.models.CharField: role>): Shows the label of the role. See get_FOO_display() for more information.

objects = <django.db.models.Manager object>

replies

Type: Reverse ForeignKey from Message

All replies of this mensaje (related name of reply_to)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

reply_to_id: Internal field, use reply_to instead.

room_id: Internal field, use room instead.

user_id: Internal field, use user instead.

class agency.models.UserPreferences(*args, **kwargs)[source]

Bases: Model

Database table: agency_userpreferences

Per-user Mission Control prefs: workspace, UI, operator, system voice.

Parameters:

desktop (JSONField) – Desktop
language (CharField) – Idioma
timezone (CharField) – Timezone
updated_at (DateTimeField) – Updated at

Relationship fields:

Parameters:

user (OneToOneField to User) – Primary key: Usuario (related name: agency_preferences)
active_workspace (ForeignKey to Workspace) – Active workspace (related name: +)
active_agent (ForeignKey to Agent) – Active agent (related name: +)
active_thread (ForeignKey to Thread) – Active thread (related name: +)
system_voice (ForeignKey to Voice) – System voice (related name: +)

user

Type: OneToOneField to User

Primary key: Usuario (related name: agency_preferences)

Accessor to the related object on the forward side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

active_workspace

Type: ForeignKey to Workspace

Active workspace (related name: +)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

active_agent

Type: ForeignKey to Agent

Active agent (related name: +)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

active_thread

Type: ForeignKey to Thread

Active thread (related name: +)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

system_voice

Type: ForeignKey to Voice

System voice (related name: +)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

desktop

Type: JSONField

Desktop

A wrapper for a deferred-loading field. When the value is read from this

language

Type: CharField

Idioma

A wrapper for a deferred-loading field. When the value is read from this

timezone

Type: CharField

Timezone

A wrapper for a deferred-loading field. When the value is read from this

updated_at

Updated at

A wrapper for a deferred-loading field. When the value is read from this

to_api()[source]

classmethod for_user(user)[source]

Get or create prefs for an authenticated user.

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

active_agent_id: Internal field, use active_agent instead.

active_thread_id: Internal field, use active_thread instead.

active_workspace_id: Internal field, use active_workspace instead.

get_next_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=True, **kwargs): Finds next instance based on updated_at. See get_next_by_FOO() for more information.

get_previous_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=False, **kwargs): Finds previous instance based on updated_at. See get_previous_by_FOO() for more information.

objects = <django.db.models.Manager object>

system_voice_id: Internal field, use system_voice instead.

user_id: Internal field, use user instead.

class agency.models.Photo(*args, **kwargs)[source]

Bases: Model

Database table: agency_photo

🖼 User photo library (chat uploads, explorer, generated).

Parameters:

id (UUIDField) – Primary key: Id
file (ImageField) – Archivo
title (CharField) – Título
origin (CharField) – Origin
source (CharField) – Source
created_at (DateTimeField) – Created at
updated_at (DateTimeField) – Updated at

Relationship fields:

Parameters:: user (ForeignKey to User) – Usuario (related name: photos)

class Origin(value)[source]

Bases: TextChoices

UPLOAD = 'upload'

GENERATED = 'generated'

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

user

Type: ForeignKey to User

Usuario (related name: photos)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

file

Type: ImageField

Archivo

Just like the FileDescriptor, but for ImageFields. The only difference is

title

Type: CharField

Título

A wrapper for a deferred-loading field. When the value is read from this

origin

Type: CharField

Origin

Choices:

upload
generated

A wrapper for a deferred-loading field. When the value is read from this

source

Type: CharField

Source

A wrapper for a deferred-loading field. When the value is read from this

created_at

Created at

A wrapper for a deferred-loading field. When the value is read from this

updated_at

Updated at

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs): Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_next_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=True, **kwargs): Finds next instance based on updated_at. See get_next_by_FOO() for more information.

get_origin_display(*, field=<django.db.models.CharField: origin>): Shows the label of the origin. See get_FOO_display() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs): Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

get_previous_by_updated_at(*, field=<django.db.models.DateTimeField: updated_at>, is_next=False, **kwargs): Finds previous instance based on updated_at. See get_previous_by_FOO() for more information.

objects = <django.db.models.Manager object>

user_id: Internal field, use user instead.

class agency.models.UiPanel(*args, **kwargs)[source]

Bases: Model

Database table: agency_uipanel

Persisted operator UIDocument. Palette = registered schema types.

Parameters:

id (UUIDField) – Primary key: Id
scope (CharField) – Scope
title (CharField) – Título
channel (CharField) –
Channel

The special ‘__interrupt__’ channel indicates that the graph execution intentionally paused and is awaiting external input (e.g. human-in-the-loop). An interrupt write is consumed when execution is resumed.
document (JSONField) – Documento
created_at (DateTimeField) – Creado el
updated_at (DateTimeField) – Updated at

Relationship fields:

Parameters:

owner (ForeignKey to User) – Owner (related name: ui_panels)
workspace (ForeignKey to Workspace) – Workspace (related name: ui_panels)

class Scope(value)[source]

Bases: TextChoices

SESSION = 'session'

WORKSPACE = 'workspace'

EPHEMERAL = 'ephemeral'

id

Type: UUIDField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

owner

Type: ForeignKey to User

Owner (related name: ui_panels)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

workspace

Type: ForeignKey to Workspace

Workspace (related name: ui_panels)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

scope

Type: CharField

Scope

Choices:

session
workspace
ephemeral

A wrapper for a deferred-loading field. When the value is read from this

title

Type: CharField

Título

A wrapper for a deferred-loading field. When the value is read from this

channel

Type: CharField

Channel

A wrapper for a deferred-loading field. When the value is read from this

document

Type: JSONField

Documento

A wrapper for a deferred-loading field. When the value is read from this

created_at

Creado el

A wrapper for a deferred-loading field. When the value is read from this

updated_at