# LangChain Source: https://docs.trysoma.ai/ai-frameworks/langchain Using LangChain with Soma Nothing to see here, move along 👀 # OpenAI SDK Source: https://docs.trysoma.ai/ai-frameworks/openai-sdk Using OpenAI SDK with Soma Nothing to see here, move along 👀 # Overview Source: https://docs.trysoma.ai/ai-frameworks/overview Using AI frameworks with Soma Framework vs runtime We view Soma as the bottom of the pyramind, providing the core building blocks for your agent and providing a DX to increase developer velocity. You can use any framework you want to build your agent, including: * Vercel AI SDK * Langchain * OpenAI Agents SDK Whilst we don't have lower level language bindings for all of these libraries just yet, you can still use them with Soma directly. Soma provides: * A secure MCP server for your agent to use * A ready to use OpenAI Streaming and Agent 2 Agent compatible API endpoints to message your agent * MCP and agent chat debug tools * An easy path from local development to production * API credential management (i.e. protect the chat endpoints via API key, Oauth, etc.) * Human in-the-loop approvals * Fault tolerance and resumability all of which compliment your chosen framework and agent / workflow business logic. # Vercel AI SDK Source: https://docs.trysoma.ai/ai-frameworks/vercel-ai-sdk Using Vercel AI SDK with Soma Nothing to see here, move along 👀 # Get runtime config Source: https://docs.trysoma.ai/api-reference/_internal/get-runtime-config api-reference/openapi.json get /_internal/v1/runtime_config Get the current runtime configuration # Health check Source: https://docs.trysoma.ai/api-reference/_internal/health-check api-reference/openapi.json get /_internal/v1/health Check the health status of the service and SDK server connectivity # Trigger codegen Source: https://docs.trysoma.ai/api-reference/_internal/trigger-codegen api-reference/openapi.json post /_internal/v1/trigger_codegen Trigger code generation for the SDK # Get agent card Source: https://docs.trysoma.ai/api-reference/a2a/get-agent-card api-reference/openapi.json get /api/a2a/v1/.well-known/agent.json Get the agent card describing agent capabilities and metadata # Get agent definition Source: https://docs.trysoma.ai/api-reference/a2a/get-agent-definition api-reference/openapi.json get /api/a2a/v1/definition Get the agent definition (capabilities and metadata) # Get extended agent card Source: https://docs.trysoma.ai/api-reference/a2a/get-extended-agent-card api-reference/openapi.json get /api/a2a/v1/agent/authenticatedExtendedCard Get the authenticated extended agent card with additional metadata # Handle JSON-RPC Source: https://docs.trysoma.ai/api-reference/a2a/handle-json-rpc api-reference/openapi.json post /api/a2a/v1 Handle JSON-RPC requests for agent-to-agent communication (tasks, messages, etc.) # Create provider Source: https://docs.trysoma.ai/api-reference/bridge/create-provider api-reference/openapi.json post /api/bridge/v1/available-providers/{provider_controller_type_id}/available-credentials/{credential_controller_type_id} Create a new provider instance with the specified configuration # Create resource server credential Source: https://docs.trysoma.ai/api-reference/bridge/create-resource-server-credential api-reference/openapi.json post /api/bridge/v1/available-providers/{provider_controller_type_id}/available-credentials/{credential_controller_type_id}/credential/resource-server Create a new resource server credential # Create user credential Source: https://docs.trysoma.ai/api-reference/bridge/create-user-credential api-reference/openapi.json post /api/bridge/v1/available-providers/{provider_controller_type_id}/available-credentials/{credential_controller_type_id}/credential/user-credential Create a new user credential # Delete provider Source: https://docs.trysoma.ai/api-reference/bridge/delete-provider api-reference/openapi.json delete /api/bridge/v1/provider/{provider_instance_id} Delete a provider instance by its unique identifier # Disable function Source: https://docs.trysoma.ai/api-reference/bridge/disable-function api-reference/openapi.json post /api/bridge/v1/provider/{provider_instance_id}/function/{function_controller_type_id}/disable Disable a function for a provider instance # Enable function Source: https://docs.trysoma.ai/api-reference/bridge/enable-function api-reference/openapi.json post /api/bridge/v1/provider/{provider_instance_id}/function/{function_controller_type_id}/enable Enable a function for a provider instance # Encrypt resource server config Source: https://docs.trysoma.ai/api-reference/bridge/encrypt-resource-server-config api-reference/openapi.json post /api/bridge/v1/available-providers/{provider_controller_type_id}/available-credentials/{credential_controller_type_id}/credential/resource-server/encrypt Encrypt a resource server credential configuration before storage # Encrypt user credential config Source: https://docs.trysoma.ai/api-reference/bridge/encrypt-user-credential-config api-reference/openapi.json post /api/bridge/v1/available-providers/{provider_controller_type_id}/available-credentials/{credential_controller_type_id}/credential/user-credential/encrypt Encrypt a user credential configuration before storage # Get function OpenAPI spec Source: https://docs.trysoma.ai/api-reference/bridge/get-function-openapi-spec api-reference/openapi.json get /api/bridge/v1/function-instances/openapi.json Get the OpenAPI specification for all function instances # Get provider Source: https://docs.trysoma.ai/api-reference/bridge/get-provider api-reference/openapi.json get /api/bridge/v1/provider/{provider_instance_id} Retrieve a provider instance by its unique identifier # Invoke function Source: https://docs.trysoma.ai/api-reference/bridge/invoke-function api-reference/openapi.json post /api/bridge/v1/provider/{provider_instance_id}/function/{function_controller_type_id}/invoke Invoke a function on a provider instance # List function instances Source: https://docs.trysoma.ai/api-reference/bridge/list-function-instances api-reference/openapi.json get /api/bridge/v1/function-instances List all function instances with optional filtering by provider instance # List provider instances Source: https://docs.trysoma.ai/api-reference/bridge/list-provider-instances api-reference/openapi.json get /api/bridge/v1/provider List all provider instances with optional filtering by status and provider type # List providers Source: https://docs.trysoma.ai/api-reference/bridge/list-providers api-reference/openapi.json get /api/bridge/v1/available-providers List all available provider types that can be instantiated # List providers by function Source: https://docs.trysoma.ai/api-reference/bridge/list-providers-by-function api-reference/openapi.json get /api/bridge/v1/provider/grouped-by-function List provider instances grouped by their associated functions # MCP SSE connection Source: https://docs.trysoma.ai/api-reference/bridge/mcp-sse-connection api-reference/openapi.json get /api/bridge/v1/mcp Establish Server-Sent Events (SSE) connection for MCP protocol communication # OAuth callback Source: https://docs.trysoma.ai/api-reference/bridge/oauth-callback api-reference/openapi.json get /api/bridge/v1/generic-oauth-callback Handle OAuth callback to complete user credential brokering flow # Send MCP message Source: https://docs.trysoma.ai/api-reference/bridge/send-mcp-message api-reference/openapi.json post /api/bridge/v1/mcp Send a JSON-RPC message to the MCP server # Start credential brokering Source: https://docs.trysoma.ai/api-reference/bridge/start-credential-brokering api-reference/openapi.json post /api/bridge/v1/available-providers/{provider_controller_type_id}/available-credentials/{credential_controller_type_id}/credential/user-credential/broker Start the OAuth flow for user credential brokering # Update provider Source: https://docs.trysoma.ai/api-reference/bridge/update-provider api-reference/openapi.json patch /api/bridge/v1/provider/{provider_instance_id} Update an existing provider instance configuration # Create data key Source: https://docs.trysoma.ai/api-reference/encryption/create-data-key api-reference/openapi.json post /api/encryption/v1/envelope/{envelope_id}/dek Create a new data encryption key (DEK) encrypted with the specified envelope encryption key # Create DEK alias Source: https://docs.trysoma.ai/api-reference/encryption/create-dek-alias api-reference/openapi.json post /api/encryption/v1/dek/alias Create an alias for a data encryption key to enable lookup by friendly name # Create envelope key Source: https://docs.trysoma.ai/api-reference/encryption/create-envelope-key api-reference/openapi.json post /api/encryption/v1/envelope Create a new envelope encryption key (master key) for encrypting data encryption keys # Delete DEK alias Source: https://docs.trysoma.ai/api-reference/encryption/delete-dek-alias api-reference/openapi.json delete /api/encryption/v1/dek/alias/{alias} Delete an alias for a data encryption key # Get DEK by alias Source: https://docs.trysoma.ai/api-reference/encryption/get-dek-by-alias api-reference/openapi.json get /api/encryption/v1/dek/alias/{alias} Retrieve a data encryption key by its alias or ID # Import data key Source: https://docs.trysoma.ai/api-reference/encryption/import-data-key api-reference/openapi.json post /api/encryption/v1/envelope/{envelope_id}/dek/import Import an existing pre-encrypted data encryption key into the system # List data keys Source: https://docs.trysoma.ai/api-reference/encryption/list-data-keys api-reference/openapi.json get /api/encryption/v1/envelope/{envelope_id}/dek List all data encryption keys encrypted with the specified envelope encryption key # List envelope keys Source: https://docs.trysoma.ai/api-reference/encryption/list-envelope-keys api-reference/openapi.json get /api/encryption/v1/envelope List all envelope encryption keys (master keys) with pagination # Migrate all data keys Source: https://docs.trysoma.ai/api-reference/encryption/migrate-all-data-keys api-reference/openapi.json post /api/encryption/v1/envelope/{envelope_id}/migrate Migrate all data encryption keys encrypted with the specified envelope key to a new envelope key # Migrate data key Source: https://docs.trysoma.ai/api-reference/encryption/migrate-data-key api-reference/openapi.json post /api/encryption/v1/envelope/{envelope_id}/dek/{dek_id}/migrate Migrate a data encryption key to be encrypted with a different envelope encryption key # Update DEK alias Source: https://docs.trysoma.ai/api-reference/encryption/update-dek-alias api-reference/openapi.json put /api/encryption/v1/dek/alias/{alias} Update the alias for a data encryption key # Create secret Source: https://docs.trysoma.ai/api-reference/secret/create-secret api-reference/openapi.json post /api/secret/v1 Create a new encrypted secret with the specified key and value # Delete secret Source: https://docs.trysoma.ai/api-reference/secret/delete-secret api-reference/openapi.json delete /api/secret/v1/{secret_id} Delete a secret by its unique identifier # Get secret Source: https://docs.trysoma.ai/api-reference/secret/get-secret api-reference/openapi.json get /api/secret/v1/{secret_id} Retrieve a secret by its unique identifier # Get secret by key Source: https://docs.trysoma.ai/api-reference/secret/get-secret-by-key api-reference/openapi.json get /api/secret/v1/key/{key} Retrieve a secret by its key name # Import secret Source: https://docs.trysoma.ai/api-reference/secret/import-secret api-reference/openapi.json post /api/secret/v1/import Import an existing pre-encrypted secret into the system # List decrypted secrets Source: https://docs.trysoma.ai/api-reference/secret/list-decrypted-secrets api-reference/openapi.json get /api/secret/v1/list-decrypted List all secrets with decrypted values (requires decryption access) # List secrets Source: https://docs.trysoma.ai/api-reference/secret/list-secrets api-reference/openapi.json get /api/secret/v1 List all secrets with pagination (values are encrypted) # Update secret Source: https://docs.trysoma.ai/api-reference/secret/update-secret api-reference/openapi.json put /api/secret/v1/{secret_id} Update an existing secret's value or metadata # Get task Source: https://docs.trysoma.ai/api-reference/task/get-task api-reference/openapi.json get /api/task/v1/{task_id} Retrieve a task by its unique identifier # Get task timeline Source: https://docs.trysoma.ai/api-reference/task/get-task-timeline api-reference/openapi.json get /api/task/v1/{task_id}/timeline Get the timeline history of a task with pagination # List contexts Source: https://docs.trysoma.ai/api-reference/task/list-contexts api-reference/openapi.json get /api/task/v1/context List all unique task contexts with pagination # List tasks Source: https://docs.trysoma.ai/api-reference/task/list-tasks api-reference/openapi.json get /api/task/v1 List all tasks with pagination # List tasks by context Source: https://docs.trysoma.ai/api-reference/task/list-tasks-by-context api-reference/openapi.json get /api/task/v1/context/{context_id}/task List all tasks for a specific context ID with pagination # Send message Source: https://docs.trysoma.ai/api-reference/task/send-message api-reference/openapi.json post /api/task/v1/{task_id}/message Send a message to a task # Update task status Source: https://docs.trysoma.ai/api-reference/task/update-task-status api-reference/openapi.json put /api/task/v1/{task_id} Update the status of a task # Chat Agent Source: https://docs.trysoma.ai/common-patterns/chat-agent Building chat-based agents with Soma Nothing to see here, move along 👀 This is an example: [example agent template](https://github.com/trysoma/typescript-ai-sdk-template/blob/main/agents/index.ts) # Combined Agent Source: https://docs.trysoma.ai/common-patterns/combined-agent Building agents that combine chat and workflow patterns Nothing to see here, move along 👀 This is an example: [example agent template](https://github.com/trysoma/typescript-ai-sdk-template/blob/main/agents/index.ts) # Workflow Agent Source: https://docs.trysoma.ai/common-patterns/workflow-agent Building workflow-based agents with Soma Nothing to see here, move along 👀 This is an example: [example agent template](https://github.com/trysoma/typescript-ai-sdk-template/blob/main/agents/index.ts) # Deployment Source: https://docs.trysoma.ai/deployment Going from local to cloud This section is a work in progress. Typical deployment pattern is: 1. Have a Dockerfile that installs the soma binary using our install script or base image. 2. Install your SDK system specific dependencies (e.g. Node.js, Python, etc.) 3. Install your SDK project dependencies (e.g. pnpm install) 4. Build your SDK project (e.g. pnpm build) 5. Set the entrypoint command to `soma start` 6. Using your container host platform, set any environment variables required 7. Let soma.yaml manage your production secrets and MCP provider credentials 8. Ensure your container has access to the AWS KMS key used to encrypt your secrets and MCP provider credentials ## Production dependencies Soma embeds these dependencies into the binary for ease of use. It's advised that you follow best practice for self-hosting these tools in a production setting or opt for their cloud managed services. You can configure credentials for Turso and Restate as parameter options to the soma start command. `soma start --db-conn-string xxx --db-auth-token xxx --restate-admin-url xxx --restate-ingress-url xxx --restate-admin-token xxx ` ### Turso / Sqlite ### Restate # Crash Recovery Source: https://docs.trysoma.ai/fault-tolerance/crash-recovery Recovering from crashes Nothing to see here, move along 👀 # Resumability Source: https://docs.trysoma.ai/fault-tolerance/resumability Resuming agent execution Nothing to see here, move along 👀 # Things to Watch Out For Source: https://docs.trysoma.ai/fault-tolerance/things-to-watch-out-for Common pitfalls and things to watch out for Nothing to see here, move along 👀 # Introduction Source: https://docs.trysoma.ai/index Welcome to Soma