Context

tac.context

Context management for the Twilio Agent Connect.

KnowledgeClient

KnowledgeClient(
    api_key: str, api_secret: str, region: str | None = None
)

Bases: BaseAPIClient

Client for interacting with Twilio Knowledge Base API.

See Enterprise Knowledge for the product overview.

Initialize the Knowledge client.

Parameters:

Name	Type	Description	Default
api_key	str	API Key for Knowledge Base authentication.	required
api_secret	str	API Secret for Knowledge Base authentication.	required
region	str | None	Optional Twilio region (e.g., 'au1', 'ie1')	None

get_knowledge_base async

get_knowledge_base(knowledge_base_id: str) -> KnowledgeBase

Fetch knowledge base metadata from the Knowledge Base API.

Parameters:

Name	Type	Description	Default
knowledge_base_id	str	The knowledge base ID to fetch (format: know_knowledgebase_*)	required

Returns:

Type	Description
KnowledgeBase	KnowledgeBase object with metadata from the API

Raises:

Type	Description
HTTPError	If the API request fails

search_knowledge_base async

search_knowledge_base(
    knowledge_base_id: str,
    query: str,
    top_k: int = 5,
    knowledge_ids: list[str] | None = None,
) -> list[KnowledgeChunkResult]

Search a knowledge base with the given query.

Parameters:

Name	Type	Description	Default
knowledge_base_id	str	The knowledge base ID to search (format: know_knowledgebase_*)	required
query	str	The search query string (max 2048 characters)	required
top_k	int	Number of knowledge chunks to return (default: 5, max: 20)	5
knowledge_ids	list[str] | None	Optional list of specific knowledge IDs to filter search results	None

Returns:

Type	Description
list[KnowledgeChunkResult]	List of KnowledgeChunkResult objects with content and relevance scores

Raises:

Type	Description
HTTPError	If the API request fails

MemoryClient

MemoryClient(
    store_id: str,
    api_key: str,
    api_secret: str,
    region: str | None = None,
)

Bases: BaseAPIClient

Client for interacting with Twilio Conversation Memory data plane API.

See Conversation Memory for the product overview.

Initialize the Memory client.

Parameters:

Name	Type	Description	Default
store_id	str	Memory store ID (starts with mem_store_).	required
api_key	str	API Key for Conversation Memory authentication.	required
api_secret	str	API Secret for Conversation Memory authentication.	required
region	str | None	Optional Twilio region (e.g., 'au1', 'ie1')	None

retrieve_memory async

retrieve_memory(
    profile_id: str,
    conversation_id: str | None = None,
    query: str | None = None,
    observations_limit: int | None = None,
    summaries_limit: int | None = None,
    communications_limit: int | None = None,
    relevance_threshold: float | None = None,
) -> MemoryRetrievalResponse

Retrieve conversation memories with semantic search and configurable limits.

Parameters:

Name	Type	Description	Default
profile_id	str	Profile ID (TTID format)	required
conversation_id	str | None	Optional conversation ID (TTID format)	None
query	str | None	Optional semantic search query (1-1024 characters)	None
observations_limit	int | None	Max observations to return (0-100)	None
summaries_limit	int | None	Max summaries to return (0-100)	None
communications_limit	int | None	Max communications to return (0-100)	None
relevance_threshold	float | None	Min relevance score (0.0-1.0)	None

Returns:

Type	Description
MemoryRetrievalResponse	MemoryRetrievalResponse with observations, summaries, communications, and metadata.
MemoryRetrievalResponse	Returns empty MemoryRetrievalResponse() if API request fails or response cannot be
MemoryRetrievalResponse	parsed.

get_profile async

get_profile(
    profile_id: str, trait_groups: list[str] | None = None
) -> ProfileResponse

Retrieve a profile by ID with optional trait group selection.

Parameters:

Name	Type	Description	Default
profile_id	str	Profile ID using Twilio Type ID (TTID) format	required
trait_groups	list[str] | None	Optional list of trait group names to include in the response	None

Returns:

Type	Description
ProfileResponse	ProfileResponse containing profile ID, creation timestamp, and traits

Raises:

Type	Description
HTTPError	If the API request fails
ValueError	If the response cannot be parsed

lookup_profile async

lookup_profile(
    id_type: str, value: str
) -> ProfileLookupResponse

Find profiles that contain a specific identifier value.

Submit an identifier object specifying the idType and value. The value is normalized using the configured identity resolution settings (such as phone number formatting) prior to matching. Multiple matches are returned if more than one profile is associated with the identifier. Returns canonical profile IDs (the earliest ID if profiles have been merged) along with the normalized value actually searched.

Parameters:

Name	Type	Description	Default
id_type	str	Identifier type as configured in the service's Identity Resolution Settings (e.g., "phone", "email"). Must be 2-30 characters.	required
value	str	Raw value captured for the identifier (e.g., "+13175556789"). The service normalizes this value according to the configured rules.	required

Returns:

Type	Description
ProfileLookupResponse	ProfileLookupResponse containing normalized value and list of matching profile IDs

Raises:

Type	Description
HTTPError	If the API request fails
ValueError	If the response cannot be parsed

create_profile async

create_profile(traits: dict[str, dict[str, Any]]) -> str

Create a profile via identity resolution (upsert).

Conversation Memory runs identity resolution on the submitted traits: if an identifier match is found the existing canonical profile ID is returned, otherwise a new profile is minted. The body must contain at least one trait promoted-to-identifier per the store's identity resolution settings, else resolution fails with 400.

The write is queued (202 Accepted) — the canonical profile ID is returned synchronously in the response body, but downstream traits may not be fully persisted immediately.

Parameters:

Name	Type	Description	Default
traits	dict[str, dict[str, Any]]	Trait-group → field → value mapping, e.g. {"Contact": {"phone": "+13175551234"}}. Max 50 groups × 99 traits each.	required

Returns:

Type	Description
str	Canonical profile ID (mem_profile_…).

Raises:

Type	Description
HTTPError	If the API request fails.
ValueError	If the response does not contain an id field.

create_observation async

create_observation(
    profile_id: str,
    content: str,
    source: str = "conversation-intelligence",
    conversation_ids: list[str] | None = None,
    occurred_at: str | None = None,
) -> dict[str, Any]

Create a new observation in Conversation Memory.

Parameters:

Name	Type	Description	Default
profile_id	str	Profile ID to associate observation with	required
content	str	Observation content (the summary text or extracted fact)	required
source	str	Source system identifier (default: "conversation-intelligence")	'conversation-intelligence'
conversation_ids	list[str] | None	List of conversation IDs this observation relates to	None
occurred_at	str | None	Optional timestamp when observation occurred (ISO 8601 format)	None

Returns:

Type	Description
dict[str, Any]	Dict with created observation details

Raises:

Type	Description
HTTPError	If the API request fails

create_conversation_summaries async

create_conversation_summaries(
    profile_id: str, summaries: list[dict[str, Any]]
) -> dict[str, str]

Create conversation summaries in Conversation Memory.

Parameters:

Name	Type	Description	Default
profile_id	str	Profile ID to associate summaries with	required
summaries	list[dict[str, Any]]	List of summary objects, each containing: - content (str): The summary text - conversationId (str): The conversation ID - occurredAt (str): ISO 8601 timestamp when conversation occurred - source (str, optional): Source system identifier	required

Returns:

Type	Description
dict[str, str]	Response dict with message field (e.g., {"message": "Summaries creation accepted"})

Raises:

Type	Description
HTTPError	If the API request fails