### Agent Spec YAML Example - Agentforce DX

Source: https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-reference

An example of an agent spec YAML file used to create an agent with the `agent create` command. This file defines properties like agent type, company name, role, and topics.

```yaml
topics:
  - name: Customer Complaint Resolution
    description: Automate customer complaints.
  - name: Employee Schedule Management
    description: Optimize employee scheduling.
```

--------------------------------

### Start Test API

Source: https://developer.salesforce.com/docs/einstein/genai/guide/testing-api-connect

Starts an asynchronous test on an agent. The test evaluates predesigned test cases that are deployed via Metadata API or the Testing Center.

```APIDOC
## POST /services/data/v63.0/einstein/ai-evaluations/runs

### Description
Starts an asynchronous test on an agent. The test evaluates predesigned test cases that are deployed via Metadata API or the Testing Center.

### Method
POST

### Endpoint
`POST …/einstein/ai-evaluations/runs`

### Parameters
#### Query Parameters
- **INSTANCE_NAME** (string) - Required - The instance of your Salesforce org.
- **TOKEN** (string) - Required - The access token obtained from Create a Token.

#### Request Body
- **testName** (string) - Required - The name of the test definition (specified in the metadata component).

### Request Example
```json
{
  "testName": "YourTestDefinitionName"
}
```

### Response
#### Success Response (200)
- **runId** (string) - The ID of the test run, used to check status and results.
```

--------------------------------

### Start a Test using Connect API

Source: https://developer.salesforce.com/docs/einstein/genai/guide/testing-api-connect

This code snippet shows how to initiate an agent test using the Connect API's 'Start Test' endpoint. It requires an instance name, authentication token, and the name of the test definition. The request body specifies the test to run.

```cURL
POST https://INSTANCE_NAME.my.salesforce.com/services/data/v63.0/einstein/ai-evaluations/runs \
Host: INSTANCE_NAME.my.salesforce.com \
Authorization: Bearer TOKEN \
Content-Type: application/json \
 \
{ \
  "testDefinition": "TEST_NAME" \
}
```

--------------------------------

### Implement GenAiCitationOutput for Predetermined Citations in Apex

Source: https://developer.salesforce.com/docs/einstein/genai/guide/citations

This Apex class example shows how to use GenAiCitationOutput for actions that require explicitly defined citations. This approach bypasses the reasoning engine, allowing direct control over the citations surfaced with the response.

```apex
public class GenAiCitationOutputExample implements AiCopilot.GenAICustomAction {
    public String process(AiCopilot.ActionContext context) {
        // Define predetermined response and sources
        String responseText = 'This response includes specific citations.';
        List<AiCopilot.GenAiSource> citationSources = new List<AiCopilot.GenAiSource>();
        citationSources.add(new AiCopilot.GenAiSource(
            AiCopilot.GenAiSourceType.WEB_PAGE,
            'External Resource',
            'Example Web Page Title',
            'https://example.com/external'
        ));

        // Create GenAiCitationOutput object
        AiCopilot.GenAiCitationOutput citationOutput = new AiCopilot.GenAiCitationOutput(
            responseText,
            citationSources
        );

        // Return the citation output object serialized as JSON
        return JSON.serialize(citationOutput);
    }
}
```

--------------------------------

### Start Session API

Source: https://developer.salesforce.com/docs/einstein/genai/guide/agent-api-examples

Initiates a new agent session. This is a prerequisite for sending messages to an agent. The response includes a sessionId required for subsequent operations.

```APIDOC
## POST /api/agent/startSession

### Description
Starts a new conversation session with an agent.

### Method
POST

### Endpoint
/api/agent/startSession

### Parameters
#### Path Parameters
None

#### Query Parameters
* **bypassUser** (boolean) - Optional - Indicates whether to use the agent-assigned user instead of the logged-in user.

#### Request Body
None (Authorization and headers are typically used for authentication and content type specification)

### Request Example
```bash
curl -X POST \
  'https://YOUR_MY_DOMAIN_URL/api/agent/startSession?bypassUser=true' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### Response
#### Success Response (200)
- **sessionId** (string) - The unique identifier for the agent session.

#### Response Example
```json
{
  "sessionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

--------------------------------

### Implement GenAiCitationInput for Dynamic Citations in Apex

Source: https://developer.salesforce.com/docs/einstein/genai/guide/citations

This Apex class example demonstrates how to use GenAiCitationInput to allow the Agentforce reasoning engine to dynamically add citations based on provided sources. It involves invoking a prompt template and retriever, then returning the response with citation metadata.

```apex
public class GenAiCitationInputExample implements AiCopilot.GenAICustomAction {
    public String process(AiCopilot.ActionContext context) {
        // Implement logic to invoke prompt template and retriever
        String prompt = 'Your prompt here';
        List<AiCopilot.GenAiSource> sources = new List<AiCopilot.GenAiSource>();
        // Add sources from knowledge articles, PDFs, or web pages
        sources.add(new AiCopilot.GenAiSource(AiCopilot.GenAiSourceType.KNOWLEDGE_ARTICLE, 'Knowledge Article ID', 'Article Title', 'https://example.com/article'));

        // Generate response using the prompt and sources
        String generatedResponse = 'This is a generated response with inline citations. '; // Placeholder for actual response generation

        // Create GenAiCitationInput object
        AiCopilot.GenAiCitationInput citationInput = new AiCopilot.GenAiCitationInput(
            generatedResponse,
            sources
        );

        // Return the citation input object serialized as JSON
        return JSON.serialize(citationInput);
    }
}
```

--------------------------------

### Agent Test Spec YAML Example - Agentforce DX

Source: https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-reference

An example of an agent test spec YAML file used to create an agent test with the `agent test create` command. This file defines properties like test name, subject type, and test cases.

```yaml
name: Resort Manager Tests
description: Tests for the Resort Manager agent.
subjectType: AGENT
subjectName: Resort_Manager
subjectVersion: v1
testCases:
  - name: Handle Complaint
    prompt: "A customer is complaining about a delayed room service order."
    expectedAnswer: "I apologize for the delay. I will investigate this immediately and ensure your order is expedited."
```

--------------------------------

### Start Test

Source: https://developer.salesforce.com/docs/einstein/genai/references/testing-api/testing-connect-reference

Starts a test asynchronously based on the provided AiEvaluationDefinition name or ID. This endpoint schedules the test and returns an identifier to track its progress. OAuth 2.0 with a connected app is required.

```APIDOC
## POST /start-test

### Description
Starts a test asynchronously based on the provided AiEvaluationDefinition name or ID. Schedules the test and returns an identifier to track its progress.

### Method
POST

### Endpoint
/start-test

### Parameters
#### Request Body
- **aiEvaluationDefinitionName** (string) - Required - The name (`DeveloperName`) of the test definition to start.

### Request Example
```json
{
  "aiEvaluationDefinitionName": "MyTestDefinition"
}
```

### Response
#### Success Response (200)
- **runId** (string) - The unique ID of the test that started.

#### Response Example
```json
{
  "runId": "test-run-12345"
}
```
```

--------------------------------

### Example Agent Spec YAML File Structure

Source: https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-generate-agent-spec

An example of an agent spec file in YAML format. It includes agent properties like 'agentType', 'companyName', and 'role' in the top section, and LLM-generated 'topics' with 'name' and 'description' in the bottom section.

```yaml
agentType: customer-facing
companyName: Sample Company
role: Assistant
companyDescription: This is a sample company.
maxTopics: 3
tone: neutral
specVersion: 1.0

topics:
  - name: Topic One
    description: This is the first topic.
  - name: Topic Two
    description: This is the second topic.
  - name: Topic Three
    description: This is the third topic.
```

--------------------------------

### Start Agentforce Conversation

Source: https://developer.salesforce.com/docs/einstein/genai/references/agentforce-mobile-sdk/agentforce-client-android

Initiates a new conversation with the Agentforce assistant. This function takes optional parameters for conversation context and returns an AgentforceConversation object, which represents the active conversation.

```kotlin
open override fun startAgentforceConversation(String?, String?): AgentforceConversation
```

--------------------------------

### AgentforceServiceImpl Constructor Parameters

Source: https://developer.salesforce.com/docs/einstein/genai/references/agentforce-mobile-sdk/agentforce-service-android

Lists the parameters required for the AgentforceServiceImpl constructor, which provides the primary implementation for the AgentforceService. These parameters include network interfaces, authentication providers, logging, and configuration settings.

```kotlin
class AgentforceServiceImpl(
    private val network: Network,
    private val domain: String? = null,
    private val sse: AgentforceServerSentEvents,
    private val credentialProvider: AgentforceAuthCredentialProvider,
    private val agentforceLogger: Logger? = null,
    private val agentforceInstrumentationHandler: AgentforceInstrumentationHandler? = null,
    private val configurationLocale: Locale? = null,
    private val agentforceConnectionInfo: AgentforceConnectionInfo? = null,
    private val agentId: String,
    private val context: Context? = null,
    private val orgId: String? = null
) : AgentforceService
```

--------------------------------

### Get Test Status using Connect API

Source: https://developer.salesforce.com/docs/einstein/genai/guide/testing-api-connect

This code snippet demonstrates how to retrieve the operational status of a specific test run using the Connect API's 'Get Test Status' endpoint. It requires the instance name and the run ID obtained after starting a test.

```cURL
GET https://INSTANCE_NAME.my.salesforce.com/services/data/v63.0/einstein/ai-evaluations/runs/runId \
Host: INSTANCE_NAME.my.salesforce.com \
Authorization: Bearer TOKEN
```

--------------------------------

### Creating an AgentforceService Instance (Kotlin)

Source: https://developer.salesforce.com/docs/einstein/genai/guide/agent-sdk-android-headless

This code demonstrates how to create an instance of `AgentforceService` for a specific agent using the `AgentforceServiceProvider`. This service is the primary entry point for managing agent communication and state in a headless Android application.

```kotlin
val context: Context = ... // Application or Activity context
val agentId: String = "your_agent_id"

val agentforceService: AgentforceService = AgentforceServiceProvider.createAgentforceService(context, agentId)
```

--------------------------------

### BotsAPI - Initialization and Properties

Source: https://developer.salesforce.com/docs/einstein/genai/references/agentforce-mobile-sdk/bots-api-android

Details on initializing the BotsAPI class and its available properties like BOT_ID and SESSION_ID.

```APIDOC
## BotsAPI Initialization and Properties

### Description
This section describes the BotsAPI class, its constructor parameters, and its properties. The BotsAPI allows access to the Bots API by sending user input and parsing the response.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Properties
- **BOT_ID** (String) - Bot identifier constant.
- **SESSION_ID** (String) - Session identifier constant.

### Initialization Parameters
- **application** (Application?) - Android application instance for context.
- **network** (Network) - Network interface for API communication.
- **logger** (Logger?) - Logging interface implementation.
- **instrumentationHandler** (AgentforceInstrumentationHandler?) - Analytics and performance monitoring.

### Methods
- **Retrieve the Bot id**
- **Get recommended utterances**
- **Log O11Y_FETCH_AGENTS_MARKER perf o11y.**
- **Sends additional context to the Bots API**

### Request Example
```json
{
  "message": "Hello, bot!"
}
```

### Response
#### Success Response (200)
- **response** (Object) - The parsed response from the Bots API.

#### Response Example
```json
{
  "reply": "Hello! How can I help you today?"
}
```
```

--------------------------------

### Example Authorization Header

Source: https://developer.salesforce.com/docs/einstein/genai/guide/access-models-api-with-rest

This example shows how to construct the `Authorization` header for API requests using the obtained JWT. The token must be prefixed with 'Bearer '.

```shell
Authorization: Bearer {token}
```

--------------------------------

### Salesforce CLI Command for Deployment

Source: https://developer.salesforce.com/docs/einstein/genai/guide/agent-namedquery

Provides the Salesforce CLI command to deploy metadata files, such as Named Query API definitions, to a target organization. Replace `<TargetOrg>` with the alias or username of your Salesforce org.

```bash
sf project deploy start -o <TargetOrg>
```

--------------------------------

### Generate Text API Request Example

Source: https://developer.salesforce.com/docs/einstein/genai/guide/access-models-api-with-rest

Example of calling the text generation endpoint. Similar to other endpoints, it requires the `modelName` in the path and standard authentication headers. The request body should contain the prompt for text generation.

```shell
POST /services/data/v60.0/models/{modelName}/generations HTTP/1.1
Host: your-domain.my.salesforce.com
Content-Type: application/json
Authorization: Bearer {token}
x-sfdc-app-context: EinsteinGPT

{
  "prompt": "Write a short poem about AI."
}
```

--------------------------------

### Initialize Agentforce Client

Source: https://developer.salesforce.com/docs/einstein/genai/references/agentforce-mobile-sdk/agentforce-client-android

Initializes the Agentforce session with required parameters including a CoroutineScope, authentication provider, mode, and application context. This function is crucial for setting up the client before starting any conversations.

```kotlin
fun init(CoroutineScope?, AgentforceAuthCredentialProvider?, AgentforceMode, Application): Unit
```

--------------------------------

### Generate Chat API Request Example

Source: https://developer.salesforce.com/docs/einstein/genai/guide/access-models-api-with-rest

An example of calling the chat generation endpoint. This requires the `modelName` in the path and specific headers for authentication and content type. The request body should be a JSON object representing the chat conversation.

```shell
POST /services/data/v60.0/models/{modelName}/chat-generations HTTP/1.1
Host: your-domain.my.salesforce.com
Content-Type: application/json
Authorization: Bearer {token}
x-sfdc-app-context: EinsteinGPT

{
  "messages": [
    {"role": "user", "content": "What is a large language model?"}
  ]
}
```

--------------------------------

### Submit Feedback API Request Example

Source: https://developer.salesforce.com/docs/einstein/genai/guide/access-models-api-with-rest

This example shows how to submit feedback using the dedicated feedback endpoint. Unlike other endpoints, it does not require a `modelName` in the path. The request body should include details about the generated text and the feedback provided.

```shell
POST /services/data/v60.0/feedback HTTP/1.1
Host: your-domain.my.salesforce.com
Content-Type: application/json
Authorization: Bearer {token}
x-sfdc-app-context: EinsteinGPT

{
  "generated_text": "This is a sample generated text.",
  "feedback": "positive"
}
```

--------------------------------

### Run Salesforce CLI Agent Preview

Source: https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-preview

This command initiates a conversation preview with a Salesforce Einstein GenAI agent using the Salesforce CLI. The `--apex-debug` flag enables Apex debugging, generating log files for troubleshooting Apex class invocations.

```bash
sf agent preview --target-org jdoe@example.com --client-app "MyAgentApp" --apex-debug
```

--------------------------------

### Configure Connected App for Agent Preview

Source: https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-preview

This snippet shows the CLI command to link a new connected app to your authenticated user. It specifies the client app name, username, client ID, and required OAuth scopes for agent preview functionality.

```bash
sf org login web \
  --client-app "MyAgentApp" \
  --username jdoe@example.com \
  --client-id YOUR_CONNECTED_APP_CONSUMER_KEY \
  --scopes "agent.profile.full offline_access"
```