Skip to content

A programming framework for agentic AI

Add API documentation (#4798)

peterychang9c8877ed664e
diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md
index 4a4439500..0dae41e78 100644
--- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md
+++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md
@@ -1,3 +1,4 @@
+(agentid_and_lifecycle)=
# Agent Identity and Lifecycle
The agent runtime manages agents' identities
diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md
index 340ad96b8..7af198f00 100644
--- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md
+++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md
@@ -12,6 +12,7 @@ will handle their messages, and a workflow can be composed of agents
with no inter-dependencies.
This section focuses on the core concepts in broadcast: topic and subscription.
+(topic_and_subscription_topic)=
## Topic
A topic defines the scope of a broadcast message.
diff --git a/python/packages/autogen-core/src/autogen_core/_agent_id.py b/python/packages/autogen-core/src/autogen_core/_agent_id.py
index 9aae843eb..de046592c 100644
--- a/python/packages/autogen-core/src/autogen_core/_agent_id.py
+++ b/python/packages/autogen-core/src/autogen_core/_agent_id.py
@@ -10,6 +10,12 @@ def is_valid_agent_type(value: str) -> bool:
class AgentId:
+ """
+ Agent ID uniquely identifies an agent instance within an agent runtime - including distributed runtime. It is the 'address' of the agent instance for receiving messages.
+
+ See here for more information: :ref:`agentid_and_lifecycle`
+ """
+
def __init__(self, type: str | AgentType, key: str) -> None:
if isinstance(type, AgentType):
type = type.type
@@ -36,6 +42,7 @@ class AgentId:
@classmethod
def from_str(cls, agent_id: str) -> Self:
+ """Convert a string of the format ``type/key`` into an AgentId"""
items = agent_id.split("/", maxsplit=1)
if len(items) != 2:
raise ValueError(f"Invalid agent id: {agent_id}")
@@ -44,8 +51,18 @@ class AgentId:
@property
def type(self) -> str:
+ """
+ An identifier that associates an agent with a specific factory function.
+
+ Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).
+ """
return self._type
@property
def key(self) -> str:
+ """
+ Agent instance identifier.
+
+ Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).
+ """
return self._key
diff --git a/python/packages/autogen-core/src/autogen_core/_agent_proxy.py b/python/packages/autogen-core/src/autogen_core/_agent_proxy.py
index f3eb70f28..09cf3c1de 100644
--- a/python/packages/autogen-core/src/autogen_core/_agent_proxy.py
+++ b/python/packages/autogen-core/src/autogen_core/_agent_proxy.py
@@ -11,6 +11,8 @@ if TYPE_CHECKING:
class AgentProxy:
+ """A helper class that allows you to use an :class:`~autogen_core.AgentId` in place of its associated :class:`~autogen_core.Agent`"""
+
def __init__(self, agent: AgentId, runtime: AgentRuntime):
self._agent = agent
self._runtime = runtime
diff --git a/python/packages/autogen-core/src/autogen_core/_cancellation_token.py b/python/packages/autogen-core/src/autogen_core/_cancellation_token.py
index 5aa449039..06e037e53 100644
--- a/python/packages/autogen-core/src/autogen_core/_cancellation_token.py
+++ b/python/packages/autogen-core/src/autogen_core/_cancellation_token.py
@@ -4,12 +4,15 @@ from typing import Any, Callable, List
class CancellationToken:
+ """A token used to cancel pending async calls"""
+
def __init__(self) -> None:
self._cancelled: bool = False
self._lock: threading.Lock = threading.Lock()
self._callbacks: List[Callable[[], None]] = []
def cancel(self) -> None:
+ """Cancel pending async calls linked to this cancellation token."""
with self._lock:
if not self._cancelled:
self._cancelled = True
@@ -17,10 +20,12 @@ class CancellationToken:
callback()
def is_cancelled(self) -> bool:
+ """Check if the CancellationToken has been used"""
with self._lock:
return self._cancelled
def add_callback(self, callback: Callable[[], None]) -> None:
+ """Attach a callback that will be called when cancel is invoked"""
with self._lock:
if self._cancelled:
callback()
@@ -28,6 +33,7 @@ class CancellationToken:
self._callbacks.append(callback)
def link_future(self, future: Future[Any]) -> Future[Any]:
+ """Link a pending async call to a token to allow its cancellation"""
with self._lock:
if self._cancelled:
future.cancel()
diff --git a/python/packages/autogen-core/src/autogen_core/_topic.py b/python/packages/autogen-core/src/autogen_core/_topic.py
index c8965a7da..67d4a246f 100644
--- a/python/packages/autogen-core/src/autogen_core/_topic.py
+++ b/python/packages/autogen-core/src/autogen_core/_topic.py
@@ -10,6 +10,12 @@ def is_valid_topic_type(value: str) -> bool:
@dataclass(eq=True, frozen=True)
class TopicId:
+ """
+ TopicId defines the scope of a broadcast message. In essence, agent runtime implements a publish-subscribe model through its broadcast API: when publishing a message, the topic must be specified.
+
+ See here for more information: :ref:`topic_and_subscription_topic`
+ """
+
type: str
"""Type of the event that this topic_id contains. Adhere's to the cloud event spec.
@@ -33,6 +39,7 @@ class TopicId:
@classmethod
def from_str(cls, topic_id: str) -> Self:
+ """Convert a string of the format ``type/source`` into a TopicId"""
items = topic_id.split("/", maxsplit=1)
if len(items) != 2:
raise ValueError(f"Invalid topic id: {topic_id}")